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Another open letter to our subscribers 

We're back again, but we're late! Over the past few months I 
have had the pleasure to. put together the first and only magazine 
specifically for Apple /// owners and users. It has been a joy for 
me to work those late nights in front of my trusty old Apple /// and 
I know by your support that I will be doing this for quite some time. 

The delays in this issue were caused by a variety of factors 
that I would like to forget. In January we mailed out a sample copy 
of the magazine to all Apple dealerships in the country. As this 
issue goes to press, a check consisting of spot calls to various 
dealers around the country reveals that less than 10% of the dealers 
who responded had received it. So much for bulk mail. 

We were counting on the response from that mailing to reach many 
more thousands of Apple /// users. Because of the snail-paced 
delivery, we have not yet been able to reach the number of Apple /// 
users that we need in order to run the quality publication that the 
/// deserves. 

Since we do not have that large a subscription base, we are 
forced to give you a February-March issue. Also a single April-May 
issue is planned. For those of you worrying about your yearly 
subscription fee, please don't. All subscribers will receive 12 
issues regardless of whether it takes 14 or 15 months to do it. This 
issue will count as one, and the upcoming April-May issue will count 
as one. Come June we hope, plan and pray that we will be able to go 
to a monthly format. 

In your own interests I therefore ask that you give your dealer 
a call and ask him to stock ON THREE. The quicker we get larger 
numbers of people reading the magazine, the quicker we will be able 
to go monthly. Again I thank you for your support. 

Sincerely , 



iS^&y^s^czr 



Bob Consorti 
Editor 
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The editors Block: 



Bob Consort! 



ns I sit down to write this column, I can't forset a phone 
conversation that I had this nnornins with a dealer. She called 
to place an order and we besan talking. She told me that she and 
all the Apple /// users in her area know that the Apple /// is one 
of the finest machines available today. 

The conversation then went to the subject of why no one is saying 
just that. Most people think that the Apple /// is a dog that needs 
to be put out of its miser/. Even Apple can't figure out why the /// 
is not selling as well as the ][. It seems that we are the first people, 
the first magazine that is trying to remedy this situation. 

How did we get in this spot? I can sum it up in one word 
-Openness -. For the two and one half years the Apple /// has 
been around, if you wanted to learn the internals of SOS, the heart 
and soul of the Apple ///, you had to spend a grand or so and 
attend a special workshop at Cupertino. Two and one half years 
and the best technical information available is the Beta draft of the 
SOS Reference Manual. 

Apple has been promising that this manual would be available 
'soon' si nee the end of 1 980. If you look on your calendar it's 1 983! 
Why is it taking so long? Read the article The ///'s For Me' in this 
issue. As Al Evans says, the explosive growth of the Apple ][ was 
the work of the "Crazies"- that strange group of people who need 
the information that Apple has not been making available. 

With the introduction of the IBM Personal Computer, IBM concur- 
rently released all of the system reference manuals. Nothing was 
held back! Look at where the IBM PC is today! The Apple ///, with 
powerful SOS is a generation ahead of anything else on the market, 
yet it is lagging far behind in sales. 

If the Apple /// had been 'open' from the start, maybe we 
wouldn't be in the situation we are in today. For the Apple /// to 
be the success that it deserves to be, three (ha!) things must 
happen. 

First of all, Apple has to develop a clearer perspective on the 
problems of the /// and become committed to supporting it 
better in the future. Part of this means that they should release all 
technical information to the general population of Apple /// 
users, and make available any information that those people ask for. 

Secondly, this magazine must publish as much of that information 
as possible to spread the various 'tricks' that your/// can be made 
to do. The most important part of the magazine aspect is the flow 
of ideas - the open forum, where people can ask questions - and 
get answers. Before we published the letter talking about the 
product by Micro-Sci that allows you to run all Apple ][ game 
software, how many people had heard about it? Without this 
forum, things can not improve. 

What is the last thi ng that must happen for the /// to be a success? 
You guessed it - People! We have to get to as many Apple /// users 




as possible. 99% isn't too 
much, for without those 
people, new ideas will go 
nowhere, and we will be 
back at the start. 



Are all these things going to happen? You bet they are! Apple 
knows that there is a problem, and they aren't as naive a company 
as some people perceive them to be. They will clean up their act, 
and start to help the /// become the success that it deserves. 

What about us? Can ON THREE do what it needs to do? I most 
certainly think so. If you look over the first two issues, you will see 
some very technical articles hidden under the guise of something 
useful that your Apple /// can do. The article 'Disk PakV in the 
January issue and the two articles 'Disk Pak2' and 'SOS Directory 
Structure Revealed' in this issue, show the user how to do some 
very interesting things with the /// while giving some information 
that was previously unknown. 

Since I don't want this magazine to become too 'techie', we dre 
also going to publish as many tutorials and reviews as we can. 
These are for the normal Apple /// user who wants nothing more 
than the information on which word processor or data base system 
is best. We have to be a 'Jack Of All Trades' and please everyone, 
or we won't be pleasing anyone! 

What's left? What needs to be done? That's right! People, we 
have to get to people. I want every Apple /// owner in the 
country to know about us so we can provide everyone with 
the kind of information that can make the Apple /// the 
biggest hit in the computer field, but I need your help! Tell a 
friend! Call your computer store and ask them to stock ON 
THREE. The more people we can reach the bigger the Apple 
/// will become, so get cracking! 

Wow! I think I got a little bit too emotional. Heck, I can't help it - 
I want the /// to succeed so badly! Remember, you can make a 
difference - so please try. 

Coming back to earth, let's take a look inside the latest issue of 
ON THREE! Al Evaris joins our ranks as a contributing author this 
month with the article 'The ///'s For Me', a short dissertation into 
the 'crazies' in this field and what they mean to the ///. Next 
month, Al will start a column entitled '/// to the Max'. It will 
contain information that enables Apple /// users to get the most 
out of his or her machine! 

In this issue I will push out a little more technical information by 
explaining the format of the SOS Directory Structure and giving 
examples of what it can be used for. One of these examples is a 
Pascal Unit and program that allows you to 'Catalog' a disk in Pascal. 

In an encore performance from last month, Martin Nichols returns 
to show you some more things you can do with that second byte 

Continued on poge 6 
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(Letters to the €c)itor) 



Dear Bob: 

Consratulations! It's been a Ions time since a new SIG (Special 
Interest Group) magazine has come out with a premiere issue as 
polished as ON THREE. The presentation, content, and general 
"feer'of the magazine are tops. The graphic information alone 
would be worth the year's subscription price. All the Apple /// 
users around here are equally pleased. 

There is one thing I would like to comment on regarding color 
monitors and the///. I, toojust experienced, firsthand, the Horror 
Story you described with the Amdek Color II. Being a dealer, I was 
able to do something which apparently you weren't. After seeing 
the glorious four colors, I sent the thing back to the distributor with 
a letter to Amdek. We were given credit with no questions asked. 
Besides the lack of colors, the bandwidth of the Color II is Insuffi- 
cient to present Apple /// 80-column text screen in an easily 
readable manner. Amdek has a reputation for producing a good 
dollar vs. quality monitor for the Apple ][ and the Apple /// 
computers. The Amdek Video 300 green screen is a good exam- 
ple. Unfortunately, the Color II does a lot to make one forget their 
better efforts. 

There is a fairly simple way to get good color in emulation mode on 
the Apple ///. Just make up a cable to connect to the Color Video 
Port, described on pages 1 32 and 1 33 of the Owner's Guide. If a 
DB-1 5 plug is available, this is the easiest way, but a very workable 
cable can be made by soldering suitable pins on the shield and 
center conductor of the cable to the monitor and plugging them 
into pins 12 and 13 of the plug. Twelve is the NTSC composite 
video, thirteen is ground. This video output into an Amdek Color I 
looks just like the same Color I connected to an Apple ][. Apple 
///video also comes from this connection, butthe Color I is hardly 
readable when looking at the Apple /// 80-column text. (The 
Color I has considerably narrower bandwidth than even the Color 
II). Apple /// color, though, e.g., the Dick Cavette show on the 
ProFile, or the Patterns and Brian's Colors from ON THREE look very 
good on the Color I. 

How do you transfer an Apple ] [ hi-res page to the Apple ///? This 
is something which is turning up more and more often in demos, so 
there must be a fairly simple way of doing it. I have heard it's 
"easy"using Pascal. Just like everything else in the world though, 
anything is easy if you know how! It would be equally useful to 
move Apple /// hi-res to the Apple ][, making allowances for 
mode incompatibilities, of course. 

Bob, if you maintain the quality exemplified in the first ON THREE, I 
predict you will have to beat off potential advertisers. While your 
advertising policy is certainly to be admired, I wonder if ON THREE 
might not, in the long run, have more to offer subscribers with the 
considerable amount of money which might become available 
from an open group of advertisers, rather than from a limited 
number of carefully screened advertisers. Looking at the matter 
purely selfishly, it might even be possible to reduce subscription 





rates and the price of the DOM's. 

Issue 2 is anxiously awaited! 

Sincerely, 

Barry W.Collins 
Alabama 

Dear Mr Collins, 

Thank you for your letter, it made my day! I hope that in future 
issues we will be as worthy of your praise. 

On the subject of the Amdek color monitor, as I look back I see 
that I didn't give enough credit to Amdek for their other 
monitors. Your letter and this line should correct that. How- 
ever, I still find it unacceptable that Amdek is still advertising 
their Color II as being compatible with the ///. 

A future issue will include a program that allows a two way 
transfer of Apple ][ and Apple /// files. Thus, you will be able 
to move pictures back and forth. 

As I said in the first issue, the decision to screen advertisers was 
difficult. As we get more and more subscribers our prices will 
drop. Until then, the only thing I can say is hang in there! We will 
grow - but we will grow at a cautious rate. 

If you have any other questions or problems, please don't 
hesitate in writing again. 

Sincerely, 

BobConsorti 

Dear Bob, 

Thanks for sending me a copy of ON THREE. Not only were we 
delighted to see a magazine directed (dedicated) to the Apple 
///, but we did get some Immediate tips from some of the articles. 

Please accept the enclosed check to initiate our subscription. We 
presently have an Apple /// with Monitor ///, Apple Disk ///, 
UPIC (which will be exchanged for a Grapplerx)^ and an Epson 
MX-100. We are presently using PFS:File, Advanced Visicalc, and 
Word Juggler. We'd like to see articles and information on uses in 
Business and Aviation areas. 

Additionally, I have recommended to John Sullivan, the owner of 
Micro Computer Store in Dayton, that he send a subscription of ON 
THREE to each purchaser of a /// system as a courtesy gesture. 

You've got a winner! 
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Best resards, 

Michael K.Farrel I 
Ohio 

Dear Mr. Farrell, 

I'm glad that you could use some information out of the first 
issue. As we receive articles, we print them, so it may not be 
very long a wait for the type of articles you desire. 

Thank you for telling your dealer about us. We need all the 
support that we can get, and your idea is great. Even if dealers 
would just send a postcard out to their Apple /// owners 
informing them of ON THREE we would grow very fast. 



Thanks again for your letter. 



Sincerely, 
Bob Consorti 



Dear Mr. Consorti, 



I am overwhelmed. What more can I say. My congratulations on a 
superior publication. I have not yet read beyond page 4 of my 
premiere issue, and I am already at the Pascal Editor to write you. 

First the comments: 

I would like to inform those thinking of buying an Epson MX-80 that 
a cabling switch has to be made for the UPIC card. A switch must 
also be installed to allow the 8th data bit to be grounded. This will 
allow full operation, including screen dumping in both Native and 
Emulation modes. 

Do you have any information on screen dumps for the AAX-80. 1 have 
heard that the PKASO card will do it, but since I have a UPIC card, I 
don't want to invest in another piece of hardware. I have heard that 
a special driver is necessary for using the MX-80 with Business 
Graphics ///. Do you suppose this driver, plus the appropriate 
program combination would work? 

I would like to change my keyboard layout (something that is 
touted as being easily done by Apple). Using Visicalc, the 
"x" could be inserted into the "-" or some other key that doesn't 
require a shift. I thought of using the Jeppson Disassembler to 
disassemble the Keyboard Layout file to try to decode it. Do you 
know an easier way? 

Are there any plans that you know of to add Auto Dial, and number 
storage to ACCESS /// (an excellent package)? I think that this 
would be a very useful addition to this program. 

Sincerely, 

Stephan M. Dorman, M.D. 
Washington 

Dear Mr. Dorman, 

Thankyou for your letter, again I hope that we will be as worthy 



of your praise in future issues. 

A few other people have responded to the question of the 
lack of color in the emulation mode. Thank you for your input. 
The item about the UPIC is notable. It's amazing that Apple 
named it the 'Universal' parallel interface card. With that name 
you would expect that you could fix the eighth bit problem 
from within software. 

Anyway, the PKASO card does do screen dumping. One way 
to do graphics screen dumps is to save the picture on disk and 
then boot Basic or Pascal and use a program to send the 
picture data to the printer. We will soon publish programs 
written in those two languages to do a screen dump to an 
Epson, thus a special driver or assembly language routine is 
only needed if you want to print pictures from within Business 
Graphics. 

IVe got a few letters out to find out where to get the necessar/ 
routines for Business Graphics. When I get a reply I will publish 
it in the magazine. 

Tm pleased to announce that Al Evans, one of our contributing 
authors, will soon show how to change the Keyboard Layout 
Table, It will be published in a few months as part of his regular 
column. 

The problem is this - it is not a code file, it is a data file. Because 
of this, programs like Dr. Jeppsons' disassembler will not work. 
Without knowledge of the structure of the layout table, the 
only way to decode it is by trial and error. This obviously takes 
some time, but we will show you how in just a little while, 

I also have a letter out to Apple about updates to ACCESS /// 
and other Apple/// software. When I know for sure 111 publish 
it. Don't hold me to it, but I understand that at NCC in June, 
Apple plans to announce quite a few updates and new pack- 
ages for the///. 

If I can be of further assitance, please don't hesitate in writing 
again. 

Sincerely, 

Bob Consorti 

Dear Bob, 

I am enthusiastic about the first issue and look foward to more 
good information inthe coming issues. I wish every success to your 
venture. 

How long do you think it might be before something equivalent to 
Quality Software's "Bag of Tricks" might become available for the 
///? That package just saved my hide on a bombed ][ data disk, so 
I've learned to appreciate what it can do. Why, you ask, am I 
emulating when I have a much finer machine available? It's 
because of a unique $500 digital-image analysis program that has 
been written only in Integer Basic. 

I've got the ProFile hard disk and the Quark series of software, both 
of which make me very pleased. "Word Juggler" is far better, in my 
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judsement, that "Apple Writer ///", but everyone has their own 
preferences, the "Spooler"and "Catalyst" prosrams from Quark 
also work very well. To avoid settins a "free" copy of your locked 
software when loadins it onto ProFile with "Catalyst", Quark clev- 
erly "fixes" your master disk so that it will no lonser boot — but it 
can be reloaded onto ProFile via "Catalyst", if that need should 
arise. 

Storins your prosrams on ProFile does permit you to 30 from one 
prosram to another without rebootins each time. I hope Quark 
sends you their products so you can do a review (me too! - Ed.). 
I've found their support to be very sood. I had some trouble 
setting their locked "Word Jussler" to boot on my ///, and they 
worked with me on the phone to solve the problem. 

My retrospective suess is that their method of disk protection 
makes the bootins of "Word Jussler" susceptible to failure on disk 
drives that run fast. Quark also recommended that I check the drive 
hub on my /// because some of the earlier versions had hubs 
slishtly out of round. If a hub on the drive is white, they recom- 
mended it be replaced with a replacement kit (costs around $12 
from Apple dealers) which uses a tan hub. have you heard of any 
reports of Apple drive problems caused by the white hubs? At 
any rate, I never did replace mine after discoverins that slowins 
down the slishtly fast speed made the bootins problem 
disappear. 

Some other new /// prosrams you misht care to review. in the 
future include "Quick & Easy Data Master", "BASIC Extension"and 
the OMNIPACK (statistics and DBM) series (all are unlocked). 
These firms desen/e our support if for no other reason than leavins 
their products open for the user to tinker with. 

I, too, sot stuck with an Amdek Color II monitor thinkins it was 
compatible with the ///. I've sot to sive Apple some blame for 
the color-interface problems, however. It is inexcusable to put a 
sisnal on the port and label it "RGB color output", when in fact it is 
not. Does anyone know what Apple had in mind when they 
desisned(?) the color output on the ///? But my story isn't as 
discourasins— my Color II does "work", after a fashion. It just 
provides different (and fewer) colors than what the Apple thinks It 
is s^neratins. How about a review of the relative merits of other 
RGB monitors on the market— some at rather attractive prices? 

My sripe is that after spendlns $500 dollars for the Microsoft Z-80 
CP/M card for the ///, I found that Microsoft's CP/M FORTRAN will 
not run on It. Oh well, at least I asked first, before also buylns the 
FORTRAN. 

A comment on the merits of drivins parallel vs. serial printers with 
the///: the story I set (thoush I have not verified It) Is that the UPIC 
output for parallel printers sets bit-8 hish, which means that some 
printers, which use 8-bits (such as the Epson AAX-series III 
Graphtrax-Plus) may have some of their features Inhibited. The 
serial port on the /// can be set up to pass al 1 8 bits when you use 
the Systems Utilities Confisuration Prosram. When I first used my 
Epson printer with the hish-bit set, the printer periodically 
switched back and forth between italics and normal fonts, but the 
anomalies disappeared when I confisured the driver to transmit 
the 8th bit. 

Are there any prosrams that will run on the /// (Includins the /// 



dialect for CP/M) that are directed toward the specific needs of 
schedullns athletic tournaments consistins of from 6 to 64 teams, 
Includins options for ratins, rankins, seedlns and schedullns the 
first-round pairinss? 

How about any prosrams that are particularly adapted to informa- 
tion manasement pertainlns to small to medium sized fire depart- 
ments? I'm concerned that I not set involved in reinventins rollins 
objects. 

One last question— is there anythins comparable (other than the 
Pascal utility) for editins Business Basic prosrams in a manner 
similar to GPLE for the ][? If not, why not? 

Sincerely, 

John M.Miller 
Alaska 

Dear Mr. Miller, 

Thank you for your letter, I enjoyed It very much. 

We are now preparing a 'Stand-Alone* package that will 
reconstruct blown disks and restore deleted files. Lazarus /// 
will be available in a couple of months. We have quite a few 
things planned, so, many such programs will become available 
in the next few months. 

Quark does make ver/ good products and we will be review- 
ing some of them in the coming months. I haven't heard of any 
problems caused by the white disk drive hubs. I do believe 
that the change to tan hubs was economical rather than 
problem oriented in nature. 

Our April-May issue will feature a review of the 'Quick and Easy 
Data Master* DBMS. Just as you say, we will support programs 
that are unlocked. This is one of the things that we look for in a 
review of a piece of software. 

Consider the story on the UPIC verified. It does have the 
problem you describe. You would think with a name like 
'UNIVERSAL* parallel interface card, you could set the 8th bit 
using the System Configuration Program, 

There is not a utility presently available that simplifies the 
editing of Basic programs. The reason is this - Almost before a 
commercial program is written, the programmer determines 
how to market it. With Apple /// programmers the problem is 
not how, but where to market it. Before ON THREE arrived on 
the scene, people could not mount a successful advertising 
campaign for their Apple /// products because there was no 
place they could find Apple /// users. Now they can. In the 
next few months we will see an explosion in Apple /// 
software. 

I have heard of an Athletic Scheduling program for the ///. I 
have an inquiry out into where you can get more information. 
When I receive the answer I will pass it on to you. I don't know 
of any information management programs that exactly suits 
your needs, so you will probally have to adapt to a particular 
software package. 
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If you have any other questions or problems, please don't 
hesitate in writing again. 

Sincerely, 

BobConsorti 

Dear Sirs: 

Enclosed is my check for $30. I find your articles and prosrams 
excellent. I would like to see more tutorials, such as "Basic - The 
Easy Way". 

I have found a partial solution to Mr. Scattersood's question, 
(Januar/ issue), resarding color in Apple ][ Emulation. My local 
Apple dealer, (Byron Johnson, of Candid Computers), rigged up 
an adapter that combines the RGB signals from the color video port 
into a composite color signal. This allows me to use an Amdek 
Color I monitor with my ///. The color quality is good in both 
Apple /// and in the Emulation mode. The resolution is not high 
enough for word processing, but this is not a problem, since a 
color monitor and black-and-white monitor can be used either 
individually or simultaneously. 

Also, I have had an adapter made which combines the two joystick 
ports into one. This allows me to use a joystick, (Cursor ///), for 
Apple ][ games in the Emulation mode. 

I have found that some Apple ][ games will run on the Emulation 
mode, and some won't. The only way to know if a game will work is 
to try it out before buying it. Could you have someone test the 
Apple ][ games and publish a list of games that are compatible 
with Apple ][ Emulation? 

Sincerely, 

John R. Cade 
California 

Dear tAr, Cade, 

I thank you for your last letter, and I think you'll be pleased to 
learn that we are planning more tutorials like "Basic - The Easy 
Way". The Pascal tutorial starts this month, and upcoming will 
even be tutorials on some of the major application programs! 

As an answer to your question, please read the following 
letter. We received it just a few days after yours. It's amazing 
how a single forum for information can spread new ideas so 
quickly. 

We're pleased to be of service, and we hope we can help you 
in the future. 

Sincerely, 

BobConsorti 

Dear Sirs: 

I very much enjoyed the premiere issue of ON THREE and I am 
looking forward to the next issue. I use my Apple/// in business, 



microcomputing consulting and sales, and for personal uses and I 
feel it is the best system available so I was very happy to see your 
publication. 

Recently I acquired a product for my/// that I was quite pleased 
with, that is the Gameport/// by Micro-Sci, the company that sells 
disk drives for Apple computers. Gameport /// is a board that 
plugs into any slot on an Apple /// and enables the user to play 
any of the Apple ][ games using an Apple ][ joystick or hand 
controllers. I have a TG Products Joystick and their emulation disk 
but I could only play a few of the games I had. I have not found an 
Apple ][ game that could not be played with the Gameport /// 
installed so I would highly recommend it to everyone. The price for 
the board and the emulation modifier disk is $74.95. 

I read your advertising policy for vendors in your premiere issue 
and was impressed with the way you will be handling advertising. 
Thanks again for a great publication, I have already recommended 
it to several of my friends. 

Sincerely, 

Roger N. Dietrich 
South Dakota 



The Editor's Block: continued 

of keyboard data. Louis Hanson makes a switch from Visicalc to 
Pascal, and in this issue starts the Pascal tutorial. Earl Curlson 
continues his popular column 'Basic - The Easy Way'. 

The Apple /// product spotlighted this month is Apple Writer 
///. The review may not be as comprehensive as last months', but 
it will show you many of the program's strong, and (ah!) weak 
points. 

Next time we get the old presses a runnin', reviews will be the big 
item. Check the New Products Received section for information on 
upcoming reviews. We will have more tutorials, and who knows 
what else! Until then, happy ///'ing! /// 



The ///'s For Me: continued 

what you're doing. I'll answer all mail and trade ideas for ideas, 
software for software. The Apple /// is a system of unknown 
potential. Let's make it more than its designers ever dreamed of. 

Here's an anecdote which may be apocryphal, but summarizes my 
point so well I can't pass it up: 

A friend of mine was responsible for the video at Steve Wozniak's 
US festival last summer. Woz stopped in at the trailer to get out of 
the heat and said something like "Boy, I wish Apples could do 
graphics like that." My friend had to explain to him that all the 
graphics for the festival were, in fact, being generated by Apple 
]['s. /// 
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The ///'s For Me 






by Al Evans 



i'm an "old-timer" in this field. I bousht my Apple ][ before disk 
drives and Applesoft, in the days when the "Red Book" was the 
only documentation. Back in those dark ases, the only microcom- 
puter prosrammers were "crazies", people with nothins better to 
do than disassemble machine lansuase to see what made the 
monitor tick. The Wizard Woz himself, when he built the original 
Apple, had no particular intention other than to build a computer 
which was easy for him to use and which he could program to play 
Breakout. 

The Apple /// is a natural evolution of the ][. It's a little faster and 
has more graphics capacity, along with a great keyboard and an 
80-column display. Many of the "tricks" that could be played on 
the ][ by means of direct RWTS calls, customized graphics routines, 
customized routines in the I/O hooks, Applesoft "ampersand" 
routines, "hidden" routines above the DOS buffers, etc. are "built 
in" to the /// as SOS calls. In many ways, the /// is a ][ which has 
fewer "knobs and switches" at the user/application level but is 
almost incredibly "adjustable" at the programmer/ system level. 

However, playing with these knobs and switches is not generally a 
part of business-oriented systems or application programming. 
Unless we have "crazies" working with the system to find out what 
it 'will' do, as compared to what it was intended to do, the 
capacity of the Apple /// will never be approached, let alone 
developed as fully as the ]['s capabilities have been. 

The Apple /// has been out for about two years. Who can tell me 
how they made those horses run in the original demonstration 
program? Where's a program to make my computer say anything 
other that "I'm Okay. Machine status normal"? 

What can we do with 256K of memory, anyway? According to my 
computer, with SOS and Pascal loaded and full graphics, this 
leaves me with enough free memory space for a complete 64K 
computer and about 20K left over. 

Or, for example, how about this: An Apple /// device driver 
doesn't necessarily have to drive a device. It's just a machine- 
language program which can do anything allowed on the "device- 
driver" level. One thing a device driver is allowed to do is "queue 
an event"; force the execution of a specified section of code (and 
"event-handler") after the boot process is completed but before 
control is handed over to the "system interpreter". An "event- 
handler" is a piece of machine code which has access to the 
higher "interpreter" level and is allowed to dojust about anything, 
including make any SOS call. 

One possible SOS call sets the .CONSOLE driver to recognize a 
specified key as an "attention event" so that subsequently, when- 
ever this key is pressed, control will pass to the "event-handler" 
originally set up by the above device driver. 

If this sets off a torrent of possibilities in your mind, you're a 
"crazy", and the future development of the Apple /// depends 
directly on you. Be advised that we are few in number and Mom 
Apple can't support us as she did the Apple ][ pioneers. Woz is 
out; she prefers to deal with middle management now. The sad 



times of cost-effectiveness has beset the computer revolution. 
Research like this is always hard to justify; you don't know what 
you'll find or how useful it will be. 

Fortunately, none of this changes what your Apple /// is - except 
to the extent that it affects what you think it is. Nobody knows what 
microcomputers are for yet! Many pretend to know; they have to in 
order to be able to say "The microcomputer of 1990 will look 
like..." or "Sales will increase X% in the business market and y% in 
the personal market by 1985..." But let's look at the record: 

In the early 1 970's, less than ten years ago, competent experts were 
saying that BASIC could not be implemented on a microcomputer. 
Two teenagers proved them wrong and became Microsoft. Their 
BASIC language is now running on nearly every microcomputer 
made. When I bought my first Apple (can it really be less than five 
years ago?), the same competent experts were stating categori- 
cally that microcomputers were fine for personal use, but just not 
reliable enough to be used in business. 

Even more recently, after I had been using that same Apple in 
business for almost two years with absolutely no serious problems, 
capable machine language programmers were telling me that the 
two games I desired most (a pinball machine and a pool table) 
could never be written. 

Fortunately, they didn't tell Bill Budge or IDSI, because both Raster 
Blaster and Pool 1 .5 became available shortly thereafter. And both 
of these, along with many other "impossible"programs, dre still 
running on that same Apple ][. 

So here we are a little later, with the Apple ///. The blind men have 
decided they definitely know what the elephant is now. They 
support those who repeat their litany of Visicalc, Word Processing, 
General Ledger, Accounts Receivable, Accounts Payable, Net- 
working, Business Graphics, data Management... And indeed, 
computerization of these functions can and will streamline the 
American way of doi ng business. But these experts do not and can 
not recognize the reality that much of the technology which makes 
it possible, both hardware and software, is the work of "crazies". 
There is no space on the balance sheet for these "unknown 
quantities". 

Back in 1978, Ted Nelson published and rriany of us signed a 
pledge that began: "The purpose of computers is human freedom. 
I am going to help make people free through computers. I will not 
help the computer priesthood confuse and bully the public..." 
Now the public is the user, running pre-packaged software which 
is mostly written for money by a second-generation computer 
priesthood, probably including many who signed that pledge four 
years ago and forgot it. And like the old, many of this new com- 
puter priesthood are afraid of those whose objective is to make the 
computer more useful to the individual by teaching the individual 
to better use the computer. 

So where does that leave us? Relatively down, but not out. We 
have to fall back and regroup. And mainly, we have to communi- 
cate, share the arcana we uncover. For a start, write me and tell me 

Continued on poge 6 



February /March 1983 



ON THREE 



/// /// /// /// /// /// /// /// /// /// /// /// /// /// 

SOS Directory Structure Reveoled by Bob consorti 



In this article I will explain the format of the directory of Apple/// 
disks. Many exciting avenues will be opened, andl will present 
examples of what can be done with this information. 

If you just want to gain 4 extra blocks of disk space, read the related 
article 'Disk Pak1 ' in last month's issue. If you want to see how to list 
the files on a directory, read the article 'Disk Pak2' in this month's 
magazine, but if you want to know the why behind the how, 
read on. 

WARNING!!!!!!!! 

The reader should feel free to experiment with the concepts 
shown here, but at all times please keep a back-up copy of any disk 
you fool with. During the course of the past few months I have 
ruined many disks with a few simple key-strokes, so I will say again 
BACK-UP THINE STUFF!! 

Format of information on 
Apple /// Disliettes 

To start off, the Apple /// uses the same 5&V4 inch, soft-sectored 
floppy disks that the Apple ][ does. As on the ][ (Dos 3.3), each 
disk can store 140-K bytes of information. On the /// a small 
amount of that space is reserved for the directory & booting 
information, so a total of 1 36.5-K or 273 blocks are left for the user. 

When a disk is formatted (by the disk formatter utility) for use, it is 
divided into 35 concentric tracks with 16 sectors per track. Each 
sector can hold up to 256 bytes of info. SOS stores information in 
two-sector units called blocks, thus each block contains 51 2 bytes 
of data. These blocks are numbered from 0-279 decimal or 0-1 1 7 
hexadecimal. 

When the /// is turned on (or whenever you boot a new d isk) the 
system turns on the internal drive and attempts to read blockO into 
the RAM at loc. AOOO hex. Block contains the second stage boot 
rputine which then takes over and tries to read in the files needed 
for the operation of the ///. 

Thus, on all Apple /// SOS disks, block is reserved for booting 
information and cannot be used for storage purposes. Likewise, 
block 1 is considered used but all it contains is two 1 's followed 
by 510 zeroes. In the article 'Disk Paki ' of last month's issue you can 
learn how to use this and other blocks which normally are reserved. 

In addition, each disk contains a directory that tells where files are 
stored on that disk. On all Apple /// SOS disks, the directory 
begins on block 2 of the diskette. 

The first four bytes in block 2 are very interesting, they are 00 00 03 
00. To understand what these bytes mean we must remember that 
SOS can be asked to 'CREATE pathname,CATALOG,length' where 
length is the number of bytes you want the directory to be. 
"Aha" you shout, now you're beginning to see the picture. (If you 
can see it this quickly you must be on top of things 'cause it took 
me weeks to get this far.) 



On a directory block, the first four bytes are a poi nter to the last and 
next blocks of that directory. I liken it to the Apple ]['s directory 
link-byte. There are 2 bytes per link-info, so if either 2-byte record 
has zeroes in both bytes there is no link. Any other number 
indicates the last or next block of the directory (Low-byte, 
high-byte) 

So in block 2, the first 2 bytes ( 00 00 ) mean that this is the first 
block of the directory, and the next 2 bytes ( 03 00 ) show that 
there is more to the directory, and the next block is #0003. The first 
4 bytes of block #3 are 02 00 04 00, showing that the last block of 
the directory was #0002 & the next block of the directory is #0004. 
Similarly in block #4 we get 03 00 05 00, but in block #5 we have 
04 00 00 00. These bytes show the last directory block is #0004 
and the third and fourth bytes tell that there aren't any more 
directory blocks - thus block #0005 is the last block of the main 
directory. 

In the BASIC manual it says that a one block long directory will hold 
up to 12 files. Since it didn't take into account the directory name 
(it also takes up a file position) we will say that one directory block 
can hold 1 3 file positions. Since we have seen there are 4 blocks in 
the main directory, simple arithmetic shows that there are (4 blocks 
X 13 files/block) = 52 file positions available on a standard main 
directory. 52-1 (for the directory name) = 51 which is the number 
of files the manual says will fit on the main directory. On some of 
the disks that come with the system this is not the case and only 1 2 
files will fit on a block. 

We have just seen that blocks 0-5 are used for booting and 
directory info. We still need some way of knowing which blocks 
are used and which are free. Block #0006 contains this information, 
which I will call the 'block bit-map'. The arrangement of 1 's and O's 
within each binary byte shows SOS which blocks are used and 
which are free. 

Each byte of block #6 can control the status of 8 blocks of disk 
space, so 280 blocks / 8 blocks per byte = 35 bytes needed for a 
normal diskette. If a bit in the block bit-map contains the value 1 , 
the block corresponding to that bit is free. If a bit in the map 
contains the value 0, the block corresponding to that bit is currently 
in use. The block bit map for a typical disk might appear as follows: 

1st byte — 2nd byte — 3rd byte — 4th-35th 
bits (0-7)-00000001 11101CX)1 11111111 all 11111111 (TF') 
block desi3nated-01234567-89ABCDEF-10 thru 17-18 thru 117 
(in hexadecimal) 

On this disk we can see that blocks '0-6' are used; 7-A' are free; 'B' 
is used; 'C is free; 'D&E' are used; and 'F-1 17' are all free. 

If you are counting along with us, you will see that for a very large 
disk drive, more than one block is needed for the block bit map. 
Since one block can be the block map for up to 4096 blocks, a 
hard disk drive will use a few of them. The largest disk that you will 
ever attach to your/// will use no more than 8. For these hard disk 
drives, the block bit map will start in block #0006 and go up to 
block #000D, depending on how many blocks dre needed. 

We have already seen how the first 4 (0-3) bytes of block 2 work, 
so starting in byte #4 dre successive 39-byte record entries. I have 
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discovered 3 different types of file entries: 1- The directory name, 2- A subdirectory name, 3- Resular files. 

On the main (or root) directory in block 2, the first file position holds the directory file and it is in the followins format. I am soins to use the 
relative byte in my numbering method, that is to say, byte ^4 of block 2 (the besinning of the first position in the director/) will become byte 

#0: 



Byte# 



Typical Value 



Meaning 



The least significant nibble (LSN) is the length of the file name. See figure 1 .0 for an explanation of 

the MSN. 

The name of the file, or in this case name of the main director/. 






F6 


1-F 


42 41 53 49 43 31 




00..00 




'BASICr 


10-17 


75 00..00 


18-19 


05 A3 


1A-1B 


00 OC 


1C 


01 


ID-IE 


00 C3 


IF 


27 


20 


OC 


21-22 


09 00 


23-24 


06 00 


25-26 


18 01 



Undetermined 

The day, month & year the file was created. See figure 1 .1 for an explanation. 

The minute and hour the file was created. See figure 1 .2 for an explanation. 

The volume number, from 0-255. In this case volume #1. 

Undetermined 

The number of bytes per file entry. 

The number of file entries per block. 

# of files on this directory. (LB,HB) 
Location of the block bit-map. (LB,HB) 

# of blocks on this disk. (LB,HB) 



For a subdirectory name entry, 


, the format is the same as the directory name entry except for bytes 23-26: 


Byte * Typical Value 


Meaning 


23-24 02 00 
25-26 08 27 


A pointer to the block number of the start of the directory (or subdirectory) on which this subdirectory 

is located. 

Undetermined. 


For a regular file entry on any directory the format is as follows: 


Byte * Typical Value 


Meaning 






2A 


1-F 


53 4F 53 2E 4B 45 52 




4E 45 4C 00..00 




'SOS.KERNEL' 


10 


OC 


11-12 


07 00 


13-14 


26 00 


15-17 


00 4A 00 


18-19 


75 A1 


1A-1B 


00 OC 


1C-1D 


00 00 


IE 


01 


1F-20 


00 00 


21-22 


75 A1 


23-24 


00 OC 


25-26 


02 00 



The LSN is the length of the file name. See figure 1.0 for an explanation of the MSN. 
The file name. 



Type of file. See figure 1.3 
Starting block of the file. (LB,HB) 

# of blocks in the file. (LB,HB) 

# of bytes in the file. (LB,HB, higher-byte) 

The day month & year the file was created. See figure 1 .1 

The minute and hour the file was created. See figure 1 .2 

Undetermined. 

File status-locked if this byte < 80, -unlocked if this byte >= 80. 

Note: You can use different values to put a different type of lock on the file. 

Undetermined. 

Day, month & year file was last modified. 

The minute and hour of the files last modification. 

Block ^ of the beginning of the director/ on which this file exists. 



Now how does SOS know where all the blocks of a particular file are on a disk? According to what's been said, the director/ information 
only gives the starting block and the number of blocks in the file. 

There dre two situations to consider. First, say your file is a short 'HELLO' program of about 250 bytes. As you can see, SOS can store that 
entire file in one block so no other linking information is needed. But what happens if you have a 5 block long file? The answer is quite simple, 
bytes ^ 1 1&12 of the file's directory entry point to the block containing the block map of that file, which holds the linking information 
needed if a file is longer than 1 block. 
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So for our 5 block file, if bytes # 11&12 of the file's directory entry 
dre 4C 00, the block map for that file would be in block #004C. In 
block #4C we misht find 4D 4E 4F 50 51 00..00. In this case the 
entire file would be in blocks 4D-51 . What happens if the blocks is 
> 256? The answer to this question is also very simple. In SOS 
notation, the block ^ (0000-FFFF) is represented in the block map 
by two bytes (LB,HB) where the LB is situated in the 1 st 256 byte 
half of the block& the HB is situated in the 2nd 256 byte half of the 
block. 

Simple arithmetic shows that one block can be the block map of a 
file with up to 256 blocks in it. That is not enough because SOS is 
able to handle much larger files. If there are more than 256 blocks in 
a particular file, byte ^'s 11 &1 2 will now point to a block that holds 
the blocks of the file's block map. Got that!?! Well, for a hypotheti- 
cal 260 block file whose starting block is #0007, block 7 might 
contain 08 09 00..00, indicating that blocks 08 & 09 contain the 
file's block map. 

Wait!, you scream. How does SOS know that it's not just a two 
block long file, but a pointer to the file's real block map? Since I 
don't know the code structure for SOS.KERNEL I can't tell you 
exactly, but I think it's a combination of some information in two 
places. First, the file entry will tell how many blocks is in the file, and 
from this SOS knows if the file is greater than 256 blocks long the 
first block is a pointer to the file's block map. Secondly, the MSN of 
the first byte of the file entry gives the exact information on how to 
read the file in. Figure 1.0 gives this information on the MSN. 

Extra blocks for free 
(wellj almost free) 

Since we can't make the disk grow, we are going to have to get 
those extra blocks I have been promising you. If you remember I 
mentioned that block #1 contains nothing but two 1's & 510 
zeroes. This is the first block we can gain. While marked 'in-use', 
when I have freed it up and then used it I have had no problems 
while using the BASIC interpreter, but... 

The Pascal system seems to dislike what I have done to my disks. It 
will store and retrieve info, on the blocks I have freed up but if you 
list the directory, it will list out all right, but it will then give the 
message: 'WARNING the directory structure is damaged on this 
volume:'. Since I have not had any problems besides that warning 
message in Pascal, I think it is okay to use the increased capacity 
disks in all applications, and I am doing so. 

4 minus 1 leaves 3, so where are we going to get 3 more blocks? 
You guessed it: the directory! The main directory uses 4 blocks and 
can hold 52 files (counting the directory name). If we free up all 
but one block ofthedirectorywe will have room for 12 files, which 
is more than enough for me. With the Apple ///'s hierarchical file 
structure and ability to create subdirectories, ! doubt most people 
would need more than 12 files on the main directory, but if you 
want to, you can later add a block or two back to extend your 
directory. 

Wait a minute! What happens if one of the directory blocks you free 
up has file entries on it? The files will become inaccessible, and 
will be lost. So to make sure you don't lose any of your files you 
must do one of the following: 



1 —If you just want to make data disks that can hold 277 blocks of 
info., format a blank disk and use the techniques presented 
later to free up those extra blocks, and then make as many 
copies of this disk as you will need. 

2— If you have a disk that already has programs and or data on it, 
use the 'Copy files' command of the system utility disk to 
transfer those files onto a disk that has been 'freed-up'. Vou can 
put up to 12 files on the new main directory, but no more! 

To free block #1 we must simply change the block bit map to 
show that it is free. For block #'s 3-5 we must not only change the 
block bit map, we also have to delete the references to these 
blocks on the root directory. If we don't do this, SOS will have no 
way of knowing that those blocks may have been used for storing 
data, and it could try to store a file entry over important informa- 
tion. There are two ways to do this, first we could write a program, 
using the Pascal language, to read in the blocks and make the 
changes needed. While possible (see the article 'Disk Paki ' in last 
month's issue), it takes a bit of code and even more time. The 
second way, which we will use here, takes only a minute to update 
a disk and will provide valuable knowledge of the workings of the 
///. 

To do this we must learn one more thing about the ///, how to get 
into and use the monitor mode. When we are in the monitor mode 
we will have access to the fast 'Read/Write a block' routine which 
makes this process easy. To get into the monitor mode first SAVE 
any program you have been working on because we will be 
resetting the entire system and you will lose any program or data 
that is in memory. Begin by pressing the 'CTRL' key & the 'Open 
Apple' key and hold them down while pressing and releasing the 
'RESET' button. You should now see a right arrow and a flashing 
underscore character (the prompt). From here you can enter the 80 
column mode by pressing the 'ESC key, then '8' & finally press 
'RETURN'. 

We can now read or write a block to a formatted disk in the internal 
drive. To do this we must understand the command which is: 

Blck<Addr1.Addr2Cmd 

where 'BIck' is the block # (in hex.) that you want to access, 
'AddrV is the starting address in memorywhere you want the 

first block to be read into, 
'Addr2' is the end address in memory that you wish to fill, 
'Cmd' is the command, either an 'R' ora 'W for read or write. 

For our purposes a similar, but shorter, form of the above com- 
mand will be used, that is: Blck<Addr1Cmd , where everything is 
the same as above, but only 1 block can be accessed at once. This 
will circumvent some of the dangers of this routine because you 
can only destroy (over-write) one block at a time. 

Therefore, the command 0000<2000R will read the OOOO'th block 
of the disk into memory starting at loc. 2000 & the command 
0000<2000W will write out the same block we just read in. 

Valid block numbers are 0-1 1 7 hex., and valid memory locations to 
read into are from OCOO to BFFF & from DOOO to EFFF. Loc.'s 
COOO-CFFF house the I/O and soft switches like the Apple ][, while 
Loc.'s FOOO-FFFF contain the monitor and some more soft switches 
(FFEF-the memory bank select, FFDO-the zero page switch, and 
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FFDF-the environment byte). Loc.'s 400-BFF dre the text screen area, and the first four pases are reserved for zero pages and a stack sred. 

Getting back to business, format a disk and before putting any files on it place the formatted disk in the internal drive of the ///. Get into the 
monitor mode and issue the following command: 0002<0C00R this reads block2 into memory at Loc. OCOO. Byte 0C02 should contain a 03, 
this is the link-info, that we want to delete, so type 0C02:00 . This change makes the main directory 1 block long but it does not free up the 
blocks we just 'de-linked'. Since we have finished with this block we can write it back to the disk with the command: 0002<0C00W . 

Some people ask me why only the first block of the directory is de-linked, and it is a very good question. The answer is, when you erase the 
linking info, in the first blockyou automatically cut off the other blocks in the directory and thus de-link the others also. It's like an Apple /// 
with 3 external drives, if they are all connected properly everything works. However, if the first extra drive is not plugged in, it and the others 
connected to it will not be seen by the system and will be considered 'off-line', or just not there. 

Now, we only have to modify the block bit map and we will be done. Read it in with the command: 0006<0C00R , and observe loc. 
OCOO. this is the first byte of the block bit map and, as previously stated, controls the status of the first 8 (0-7) blocks. It can normally have only 
two values, a 00 or a 01 . The 00 tells that all the blocks in that subgroup (0-7) are used while the 01 says that only the 7th block is free. Since 
we want block #'s 1&3-5 marked free, we must find the hexadecimal equivalent of the binary number 0101 1 100 or 0101 1 101 , where the 
right most bit is a or a 1, depending on the original value. 

If the value of byte OCOO is a 00 we must change it to 0101 1 100 or 5C hex. If it is a 01 , change it to 0101 1 101 or 5D hex. Once you have 
changed byte OCOO to the new value you can write it back to the disk with the command: 00060C00W . All done!! See, it wasn't too 
hard. 0ei<OClOoW 

Now, if you boot a BASIC diskand catalog the disk you just updated, you will see that you now have 4 extra blocks of disk space! On an SOS 
disk only 3 blocks are needed, block 0-the booting info., block 2-the main directory, block 6-the block bit map. A full 138.5K-bytes of 
storage is now available on each diskette. 

There is one more thing that you might have noticed, when you catalogued the new disk, SOS only had to search through 2 blocks of 
information (the 1 block long directory and the 1 block long block-bit map) instead of the normal 5. This change has resulted in a slight 
decrease in the time needed to locate a file. 

YeSg there is room for one more file! 

The most frustrating part of the past few months has been trying to figure out why some disks would only hold 1 1 files on the main directory. 
All subdirectory blocks could hold 12, and I was ata loss to explain this difference. Since the first directory block holds the directory name I 
expected it would hold 12 more files, for a total of 13, but noil 

At the peak of frustration I found that the first block of a subdirectory would hold 1 2 files in addition to the subdirectory name file. At this 
point I felt like burning all my SOS disks, and I stopped trying to figure it out for a few weeks. A little while later it came to me and I felt like a 
real jerk 'cause it isn't that hard to understand. 

I compared a subdirectory and a main directory and found that on a main directory, byte 20 of the directory name entry contains a 'OC but 
on a subdirectory it held a 'OD'. Eureka! This byte controls the ^ of entries per directory block! 

Using the methods presented earlier I changed that byte in the directory entry to 'OD' and sure enough I was able to store a total of 1 3 files on 
the main directory blocks. As a sort of a review, lets go ahead and change it. 

Get into the monitor and read in the first block of the directory with the command '0002<0C00R', now enter '0C24:0D' & then write it back to 
the disk with the command '0002<0C00W'. DONE!!! 

Another thing that frustrated me was the fact that the Pascal system for the /// has the same error. Since it had the new SOS 1.1,1 expected it 
to have the correct directory structure, and when it didn't I thought there might be something in there that I couldn't see. 

I traced down the error to a single byte on the old SySTEM.UTILIT/ disk. One lousy byte had me going without sleep for a few days! Anyway 
this is only a problem with disks formatted by the old (Version 4.0) of the SYSTEM. UTILITY disk. The new version (which everyone should 
have by now) does it the right way. However, the new 'BASIC disk. Version 1 .1 also has this problem. I think that the Pascal system disks and 
the BASIC disks were initially formatted with the old version and wer^ subsequently duplicated, and that is why they have the incorrect 
structure. You should check byte 24 of block #2 of any disk you may have copied from the master disks. If it's not 'OD', change it! 

That's all folks. Have fun using the ideas presented here, but remember to try it out on an empty disk first. If you make an error you could easily 
lose an entire disk. Coming soon I will present a program that does a complete verification of your disks. You will be able to stop those 'Bad 
Blocks' before they ruin your important data! 
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Figure 1 .0 



The MSN of a f\ le's directory entry acts as a 
flas for SOS in determinins how to read 
the file described in the file's directory 
entry. 

(See the article on the meanins of a file's 
'block map' and how SOS reads a file's 
blocks) 



MSN Explanation: 

1 —Tells that the file's block lensth is 1 and the block is data. 

2— Tells that the file's block length is greater than 1 but less than 256 in length, and that the first 

block of the file is the file's block map, not data. 
3— Tells that the file's block length is greater than 256 blocks in length, and that the first block 

of the file is a poiriter to the files block map. 
D— Shows that this file is a 'Catalog' or directory file. 
E— Shows that this is a sub-directory. 
F— Shows that this is a main directory. 



Figure 1 .1 



Value of 
Byte* 18,19 



Resulting Date 
MONTH/DAy/YEAR 



Explanation: 



byte #19 — ► An even LSN sets the months 0-7. 
An odd LSN sets the months 8-12. 

The MSN sets the year according to year = INT (Byte 19/2-I-.5) & if byte 19 is 
oddyear=year-1. 

byte #18 —► This sets the day & month according to month=INT (Byte 18/32) & day=INT 
((byte 18/32-month) *32-h.5) & if byte #19 is odd month = month + 8. 



00 00 


00/00/00 


01 00 


00/01/00 


01 01 


08/01/00 


00 02 


00/00/01 


00 AO 


00/00/80 


00 A1 


08/00/80 


00 A2 


00/00/81 


81 A2 


04/01/81 



Figure 1 .2 



Value of 
Byte#1A, 1B 



Resulting Time 
HOUR:MINUTE 



Explanation: 



00 00 

01 00 
20 00 
OC 01 
OC 17 



00:00 
00:01 
00:32 
01:12 
23:12 



byte #1 A — ► Controls the minute (0-59) 
byte #1 B — ► Controls the hour (0-23) 

Values greater than 59 or 23 (dec.) are treated as by the Pascal filer, but Basic sees them as 
they are, with no checking to find if they are legal. 



Figure 1 .3 

Byte # 10 controls the type of file in the following format: 


From BASIC 


From BASIC From Pascal 


From Pascal 


Value Type 


Value Type Value Type 


Value Type 



00 


UNKNOWN 


01 


BAD 


02 


PASCOD 


03 


PASIXT 


04 


TEXT 


05 


PASDTA 


06 


BINARY 


07 


FONT 



08 


FOTO 


09 


BASIC 


OA 


DATA 


OB 


WPTEXT 


OC 


SYSTEM 


OD 


RESERV 


OE 


RESERV 


OF 


CAT 



00 


Unknown 


01 


Badfile 


02 


Codefile 


03 


Textfile 


04 


Asciifile 


05 


Datafile 


06 


Datafile 


07 


Fontfile 



08 


Fotofile 


09 


Basicpros 


OA 


Basicdata 


OB 


WPtext 


OC 


Sosfile 


OD 


Datafile 


OE 


Datafile 


OF 


Directory 




12 
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Disk PQk2; Listing Files In PqscqI by Bobconsom 



HOW many times has this happened to you? Working with a 
program, you need to retrieve information from a certain file, 
only you have forgotten its name. No problem right? - all you need 
to do is catalog the disk. Oh no! Vou can't do that from within the 
program. A few minutes later, after you boot a disk that you can 
catalog a disk with (Basic, Pascal filer...) and see that the darn file is 
named 'XyZ01.3' instead of 'XyZ01.2' you mutter to yourself - 
"There's got to be a better way...". 

Since these computers are supposed to save us time, there does 
have to be a better way! - and here it is. A program written in Basic 
can give the user the option of CATALOGing a directory because 
the word 'CATALOG' is part of its vocabulary. Pascal, however, has 
no similar command. True, you can use the filer to list the directory, 
but we need something that we can use within a program. 

The Pascal Intrinsic Unit list-Stuff' (Program Listing #1) is the 
answer. It gives Pascal programs the ability to list the files on any 
directory or subdirector/. Thus, all programs written in Pascal can 
now give the user the option of seeing a complete file listing. 
Extremely versatile - it will send the output wherever you want 
('.CONSOLE', '.PRINTER', disk-file...), list the files on an arbitrar/ 
sized viewport, and it even returns error messages if anything goes 
wrong. 

'List-Stuff' gives the user the option of pressing the 'ESCAPE' key to 
exit the listing. Thus, if you are in the middle of a two hundred file 
listing and want to exit -Press 'ESCAPE'. Another thing that 'List- 
Stuff' allows is the starting and stopping of the listing whenever a 
key is pressed. This comes in handy if you want to temporarily stop 
the listing and don't want to type 'CONTROL-7'. 

This Unit is based on the information in the article 'SOS Directory 
Structure Revealed'. That article is for those of you who want to 
know the why behind the how, and aren't satisfied with typing in 
the programs. If you want to learn a little more, by all means read it- 
you may well get something out of it. 

Disk Pak2: Internals 

I wrote this routine as an Intrinsic Unit so that all Pascal programs 
could easily use it. Though, you can easily change it to a Segment 
Procedure if needed. I tried to make the program as simple and 
easy to read as possible, so it is not as fast as a Basic CATALOG or a 
Pascal Filer List command. However, it does give quite a bit of 
information that those commands do not. 

I promised myself not to use assembly language (too hard to read), 
but promises are made to be broken. In the interests of some kind 
of execution speed I used the SOS call 'VOLUME' to determine the 
number of free blocks available on a volume. All of the file informa- 
tion parsing is done in Pascal so you can understand it easier. 

Turning now to the Unit 'List-Stuff', we see that the Pascal host 
program can communicate with the Unit through the means of the 
PUBLIC procedure 'List-SOS-Directory'. As the listing says, the call- 
ing program must give 'List-SOS-Directory' three things. The path- 
name of the directory you want to list, the pathname of the output 



file, and the number of lines on the current viewport. The Unit will 
list the director/ (if possible), and return with an error code and 
message if anything goes wrong. 

On an interesting note, I used the compiler option '[$E+]' to allow 
for provate files within the 'IMPLEMENTATION' of a UNIT. While not 
mentioned in any of the Pascal manuals supplied with the Pascal 
language system, the upcoming Apple/// Pascal Technical Refer- 
ence Manual documents it. By using this option, you will regain the 
1K bytes of the I/O buffer used for the file when the UNIT 
terminates. 

The T/PE definitions tell the story well, a Root Entry (the volume 
name & info.) and a File Entry (the file name & info.) are both 
records containing the various fields corresponding to the informa- 
tion stored in the disk directory. This is done so that we can read 
the director/ block directly into the record. 

While correct on paper, there is a problem. When you PACK a 
variable in Apple /// Pascal, the fields within the records can not 
cross a word boundar/. Thus, to be packed correctly - all the fields 
must have a length of a multiple word (an even number of bytes). 
That's right, each directory record on the disk is 39 bytes long. It 
complicated matters somewhat, and that is the reason for the 
MOVELEFT's in the procedures 'Get-root-info' and 'Get-file-info'. 

I used a rather complicated routine in opening the output file. 
While most of the time you will be sending the output to the 
console, you may want to get a hardcopy of the listing. The 
procedure 'Set-Out-device' checks if the output file is on a disk 
and if so it adds a '.TE>Cr' to the end of it so that it generates a Pascal 
Textfile and not an Ascii file. Complex I/O error checking assures 
that the program will not crash, even when you type in a non- 
existing director/ or bad file name. 

Thecode'CHR(xxDIV10 + 48)andCHR(xxMOD10 + 48)'isused 
extensively throughout the routine to give a formatted screen 
output. It will write out a two digit number, but instead of leading 
spaces, it gives leading zeroes. 

One interesting piece of information that the routine returns when 
listing a directory is this: It writes out the number of blocks that the 
files data occupies and the number of blocks that the entire file 
takes up on the disk. These are not the same due to SOS using some 
overhead 'housekeeping' blocks. The routine will also list the 
number of bytes that the file uses. Since a file may be up to 16 
megabytes long, this can be a big number and that is why I used 
Long Integers in computing them. 

Program Listing #2 is the assembly language routine that returns the 
number of free blocks of the device name passed to it. It is fairly 
simple and will only return the number of free blocks if a block 
device name is passed to it. A volume name or subdirectory will 
not work! 

Program Listing #3 is the Pascal program that uses the Intrinsic Unit 
'List-Stuff' to list the contents of any directory. This program is also 
very simple. Notice that we set up a window on the screen with 
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/// /// 



the dimensions 20X80. We then call the procedure List-SOS- 
Directory with the appropriate parameters. Notice that the pro- 
Sram never properly ends because 2+2 never stops bei ns equal to 
4. To leave the program, type 'ESCAPE' and then 'RETURN' vs/hen 
asked for the output file. 

To use this Unit, type in Program Listing #1 and compile it v^ith the 
name 'UST.STUFF'. Next, type in Program Listing #2 and assemble it 
v^ith the name 'VOLUME'. Now, use the linker to join together the 
assembly language routine (Listing #2) and the Unit (Listing #1 ). 
Si nee you may not have that much experience we wi 1 1 go through it 
step by step. 

First, make sure the linker (SYSTEM. LINKER) is available on one of 
your disks. At the main command level, type the 'L' key - but don't 
press 'RETURN' yet. When the prompt says 'Host file?', enter 'LIST- 
.STUFF'. Now if all goes well, the next prompt should say 'Lib file?'. 
For this one, enter 'VOLUME'. Since these dre the only fi les we want 
linked, when the prompt again says 'Lib file?', press 'RETURN'. Press 
'RETURN' once again when the screen reads 'Map file?'. Finally, 
when the screen says 'Output file?', type in 'LIST.STUFF'. There, all 
done! We now have a useable library Unit. 

Next, use the librarian to add the Unit to your SYSTEM. LIBRARY. At 
the main command level X)ecute the file 'UBRARY.CODE'. When 
the screen prompts you with 'Output file — ►', enter 'NEW.LIB'. 
Make sure that the diskette you are putting 'NEW.LIB' on has enough 
room to hold the sum of the old library and a little bit more. When 
the screen prompts you with 'Input file — ►', enter '.D1/SYSTEM.- 
LIBRARY'. Now type '=' to copy all the library segments from the old 
library to the new one. 

When the disk drives have stopped making noise, type 'N' then 
'UST.STUFF' and now press 'RETURN'. Now look on the screen 
under the prompt 'Output file — ♦' and find the first two slot 
numbers that aren't occupied. Type 1 <space> 1st empty slot 
number <space> and then 2 <space> 2nd empty slot number 
<space>. Finally type 'Q' and then enter any copyright noticeyou 
want to include. Lastly, use the filer to remove the old 'SYSTEM.- 
LIBRARY' and to transfer this new library onto your system diskette 
with the new name 'SYSTEM.LIBRARY'. 

Once you have correctly installed it, all of your programs can use it. 
Finally, type in Program Listing ^3 and compile it. You can now 
execute this file and test the new Unit. 

That's about it for now. Nexttimel will present another handy utility 
that will allow you to list the files on an Apple ][ DOS 3.3 diskette 
from Apple /// Pascal. If you think this is leading somewhere, 
you're right. In just a little while, you will be able to inexpensively 
transfer Apple/// SOS and Apple] [(e) DOS 3.3 text and graphics 
files! /// 





■ nnurvu 

PLA 


ru\i 




STA 


XI 




PLA 






STA 


Xi+i 




.ENDH 






.MACRO 


Push 




LBA 


7.i+i 




PHA 






LDA 


XI 




PHA 






.ENDfi 






.PROC 


S0S>laie,5 




JHP 


Begin 


303 Bik 


.EQU 


1 


ParanO 


.BYTE 




Parami 


.BYTE 




Para»2 


.BYTE 




Parafi»3 


.BYTE 




Paran4 


.BYTE 




ParaiS 


.BYTE 




Parai6 


.BYTE 




Para«7 


.BYTE 




Para«8 


.BYTE 




Begin 


Pop 


Return 




Pop 


ErrPtr 




Pop 


FreBIks 




Pop 


TotBlks 




Pop 


VolNaue 




Pop 


DevNaAe 




LDY 


too 




STY 


Para»4 




STY 


Paraii2 




LDA 


tVolNaae 




STA 


Parai3 




LDA 


lOevNaie 




STA 


Parasl 




LDA 


104 




STA 


ParaiO 




BRK 






.BYTE 


Voiuie 




.WORD 


SOS Bik 




STA 


9ErrPtr,V 




LDA 


Parai? 




STA 


^FreBik5,Y 




LDA 


ParaiS 




STA 


3TotBlk5,V 




TYA 






I NY 






STA 


aErrPtr,y 




LDA 


ParaiB 




STA 


9FreBik5,Y 




LDA 


Paraffi6 




STA 


aTotBlk5,V 




Push 


Return 




RTS 





;Puii a word troa the stack 



jPush it back on 



;Set up the paraaeter area 



; Issue SOS call # C5 tVoluie) 

;Set up pointer to paraneters 
; Store the error code high byte 

jStore the free blocks high byte 

jStore the total blocks high byte 

; Store the error code low byte 
jStore the free blocks low byte 
;Store the total blocks low byte 



Disk Pak2: Program Listing #2 



.END 



Return .EQU 
Voluie .EQU 
DevNase .EQU 
VolNase .EQU 
TotBlks .EQU 
FreBIks .EQU 
ErrPtr .EQU 





0C5 

OEO 

0E2 

0E4 

0E6 

0E8 



I'm 



tmmmmmmmnmmmmmnmmmm 

Disk Pak2i Set Voluie Info 



I } 
$ > 

This asseably language procedure will return t ) 
I of free blocks, the i of total blocks and t } 
the voluie nate of the device naie passed to it. I ) 

mtmmmmmtmmtmmmmmmmmtt > 
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Disk Pak2: Program Listing #3 



PROBRAM Listjt; 

{ itititttttttmtttttttttiimitttHttittiittMtttitttttimitttmiitintt 

X 

Disk Pak2i List it I Copyright 1982, 1983 by I 
I ONTHREE I 

by Bob Consort i i February-Harch, 1983 I 



{ 
{ 

{ t 
{ t 
{ t 
{ I 
C t 
{ I 
{ t 
{ t 
( 



This prograi uses the Intrinsic unit 'List_Stuff' to list the 
contents of any directory. Note that you can define the nuiber of 
lines to be listed per page. Thus, you can set a vieMport and list 
the files according to the size of that text NindoH. 



{ tmmmuuummmtmmummmmmmmmtttumtmmt 



USES List Jtuff? 

CONST Bell = 7; 

Top viewport = 2; 
norial = 17! 
inverse = l8| 
Escape = 27; 
Clear_vieiiport = 28; 

TYPE Counter = INTE6ER; 



VAR In Path, Out Path: STRINB; 
Error isg: STRINSs 
Error Icode: INTE6ER: 
Lines.on.MindoN! INTE6ER; 



{ Contains the routines to list a directory ) 

{ Causes a beep on the internal speaker > 
{ Sets the top of the currently defined viewport } 
{ Sets norial video output (Mhite on Black) ) 
{ Sets inverse video output (Black on White) ) 
{ The ASCII nuiber of the ESCAPE character ) 
{ Hoies the cursor and clears the viewport ) 



{ The input and output files > 

{ Holds the error lessage and nuiber } 

{ returned by the Intrinsic Unit List .Stuff } 

{ The nuiber of lines in the current viewport ) 



PROCEDURE Set titles; 
VAR i: Counter; 



{ Sets the lain page heading for the entire prograi > 



BE6IN 

MRITE (CHR (Clear viewport)); 

WRITE ('Disk Utility Pak2'); 

60T0XY (60. 0); 

WRITELN ('Copyright 1982, 1983'); 

URITE ('by Robert Consorti'); 

60T0XY (64, 2); 

NRITELN ('by ON THREE'); 

FOR i := 1 TO 10 DO 
NR I TE ( ' •""• ' ) • 

NRITE (CHR (Top viewport)) 
END; { of PR0CED0I?E Set.titles > 



PROCEDURE Print Error; { Routine to print out the error lessage > 
VAR Ch: CHAR; ' 

BE6IN 

NRITELN (CHR (Bell)); 

IF (LEN6TH (Error isg) = 0) THEM 
NRITELN ('HARNIR6: Error I', Error code) 

ELSE 
HRITELN ('HARNIN6: ', Error isg); 

BOTOn (0.23); 

URITE (CHR (inverse), 'Press any key to continue', CHR (norial)); 

READ (KEYBOARD, Ch) 
END; { of PROCEDURE Print .Error } 

PROCEDURE Bet Paths; 
BE6IN 

HRITELN (CHR (Clear viewport)); 

NRITELN ('(RETURN for ".CONSOLE", ESCAPE RETURN to exit)'); 

WRITE ('Enter where I should send the listing -> '); 

READLN (Out Path); 

URITELN* 

IF (LEnIth (Out Path) = 0) THEN 
Out Path := 'ICONSOLE'; 



IF (Out Path [1] ^ CHR (Escape)) THEN 

EXIT IPROBRAH); 
WRITE ('Enter the directory to list -> '),• 
READLN (In Path) 
END; { of PROCEDURE Bet Paths ) 



BE6IN { Hain prograi } 
Setjitles; 

Linis on window i- 20; { There are twenty lines on this viewport ) 
REPEAT - 
6et_Paths; 
Error code .•» 0; 
Error "isg ;- "; 

List SOS Directory (In Path, Out Path, Lines on window. Error code, Error isg); 
IF (Error code <> 0) TBEN * 
Print Error 
UNTIL (2 + 2 <> 4) 
END. { Of PR06RAH List.It ) 

Disk Pak2: Program Listing #1 

UNIT Listjtuff; 

i%l* } i This coipiler option allows for private files within the UNIT ) 

{ tnttuttituittttttuuiiuumintntututttumttttiittutttitttttitt > 
{ I t } 

{ t Disk Pak2: Directory Lister Unit 1 Copyright 1982, 1983 by I $ ) 
( I } ON THREE 11) 

{ I by Bob Consorti 1 February-Harch, 1983 \ t ) 

i t t } 

{ t This Intrinsic Unit gives any Pascal prograi the ability to list the t ) 

{ t files on any directory or subdirectory. Thus, all prograis written t } 

( I in Pascal can now give the user the option of seeing a coiplete file I } 

{ I listing. t > 

{ I t } 

{ t Please read the article and the prograi List.It to see how to install t ) 

{ t and use this Intrinsic Unit. ~ I ) 

(I t ) 

{ ttttiiiiutittttttmitttumtttnmmtmtttttittttttmtmitttttttm > 

INTRINSIC CODE 24; { Only one seoient: files are private to this UNIT ) 
{ because of the 'E^' coipiler option shown above. ) 
INTERFACE 

PROCEDURE List.SOSJirectory (VAR Pathnaie, Out .Path: STRINB; 
VAR Lines on window. 
Error: INTEBER; VAR Error.iessage: STRINB); 

IHPLEHENTATION 

{ tmmtmmummtmmmumtummtmtmmmmmmtnm > 



{ t 

{ t 
i t 
i t 
i t 
i t 
{ I 
{ I 
{ t 
{ t 
{ I 



The procedure 'List .SOS Directory' is PUBLIC and can be used by your 
Pascal host prograi' as follows: 

INPUT to List SOS Directory: 

1) Pathnaie - Tfie directory you want to list. 

2) Out .Path - Where to send the listing. 

3) Lines.on.window - The current nuiber of vertical lines in the 

viewport. Used to deteriine where to lake a 
page break when listing to the '.CONSaE'. 



{ I Output froi List SOS.Di rectory: 
it 1) The listed Bi rectory. 

2) Error - The error code (as indicated by lORESULT) for the last 
coipleted Input/Output operation. 

3) Error lessage - The STRINB consisting of the error lessage fw the t ) 
lORESULT. If eipty, the error is not included in t } 
in the 'Error.type^ ARRAY. t ) 



{ t 
{ t 
{ I 
{ I 
< t 
{ 



t } 
$ ) 
t } 
t > 
I } 
t } 
t } 
t > 
I } 
t } 
t } 
t } 
t } 
t } 
t } 



{ mmnmmmmmmmmummmmtmmmmmtmmmm > 
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PROCEDURE SOS Voluae (VAR Dev Niae, Vol Naae, Tot Blocks, Free Blocks, 
Ret .Code)? EXTERNAL; 

PROCEDURE List SOS Directory; 

CONST norial "^ 17; { Sets noraal video output ^Hhite on Black) ) 

inverse ^ 18; { Sets inverse video output (Black on White) > 

clear vienport - 28; { Hoies the cursor and dears the viewport } 



TYPE Counter = IMTEBER; 



Byte 


M..255; 


Point 


= RECORD 




Last blk: 1NTE6ER; 




Nexfblk: INTEBER 



{ Pol lotting are the TYPE definitions } 
{ that are the building blocks oi the > 
{ the directory structure. > 



END; " 
Lgth rec = PACKED RECORD 
Lens 0..15; 
Typ; 0..15 
END; 
StringlS = STRlMB CIS]; 

Filekmd = (Unknown, Badfile, Codefile, Textile, AsciiHle, Datafile, 
Binary, Fontfile, Fotofile. Basicprog, Basicdata, MPtext, 
Sosfile. F typeU, F typei4, Sos directory); 
Filler I = PACKED RECORD 

MlO, Nil, ifl2, Ml3: Byte; 
Nl4, Ni5, n16, n17: Byte 
END; 
Date rec = PACKED RECORD 
Day: 0..31| 
Honth: 0.,12; 
Year; 0..99 
END; 
Tiie rec = PACKED RECORD 
Hinute: Byte; 
Hour: 0..31: 
Filler; 0..7 
END; 



Vol nui 
Fiirer2 



pXck^d 



RECORD 

Byte; 

Byte 



Byte 



NlD: 
«1E: 
END: 
Entry info » PACKED RECORD 

Byte_per_entry; Byte; 

File'entries per block: 
END; ■ " * 
Root Entrys RECORD < This is the root directory definition ) 

Len: Loth rec: 

Naae: StrfnqlS; 

Hastel: Fillerl: 

Create date; Date rec; 

Create" tiie: Tiae'rec; 

Vol: Vol nua; 

Haste2: Filler2: 

Entry; Entry into; 

Files on dirT INTEBER; 

Bit aap Toe; INTEBER: 

Blki on'disk; INTEBER 
END; "" ' 
File.Entry= RECORD { This is a file definition ) 

Len; Loth/ec; 

Naae; StrfnqlS; 

F type: Filekind: 

Sfart blk; INTEBER; 

Nua biks; INTEBER; 

Nua'bytes: PACKED ARRAY £0..2] OF Byte; 

Create.date; Date.rec; 

Create'tiae: Tiae'rec; 

Mastell INTEBER; ~ 

F status: Byte; 

Naste2; INTEBER; 

Hodjate: Date.rec; 

Hod'tiae: Tiae'rec; 

Dir'start; INT£6ER 
END; " 



Dir List = RECORD 

Last.Next: Point; 
Root: Root Entry; 

Files: PACI^ED ARRAY CO.. 12] OF File Entry 
END; 

VAR Infile: FILE; ( Directory path to list > 

Device; TEXT; { Nhere to send the listing ) 

File count, Line count, Count : Counter; { Teaporaries used for control ) 

Bloci buf: PACKED ARRAY CO.. 511] OF Byte; { Buffer variable } 

File fype: ARRAY CO.. IS] OF STRINB ClO]; C An array of file types ) 

Error type: ARRAY CI.. 127] OF STRINB; { An array of error aessages > 

Directory: Dir_List; { A directory block > 



DO 



PROCEDURE Set Error types; 
VAR i; Counter; 



BEBIN 
FOR i := 1 TO 127 
Error _type Cil : 
Error type C2] ;* 
Error" type C3] :» 
Error_type C4] ;= 
Error" type C5] := 
Error 2type C7] ;= 
Error" type CBl ;= 
Errorjype C9] i' 
Error^^type CIO];* 
Error "type ClU:* 
Error" type C12];= 
Error lype C16];= 
Error .type iZhh' 
Error "type C37]:= 
Error' type C45];= 
Error "type CA4];= 
Error"type C68];s 
Error type C69];s 
Errorjype C70]:= 
Error "type C73]:= 
Error" type C78]:= 
Error "type CBO]:^ 



{ Sets the error aessages ) 



Error" type C87]: 
END; { Of PROCEDURE 



{ Null out the strings, ) 
= "; { or you will get errors. 
'Bad unit nuaber'; 
'Illegal operation'; 
'Illegal directory spec'; 
'Lost unit - no longer on line'; 
'Illegal pathnaae'; 

'No rooa - insufficient space on diskette'; 
'No unit - unit is not on line'; 
'No such file in specified directory'; 
'Duplicate pathnaae'; 
'Atteapt to open an already open file': 
'Nri te-protect error - diskette is protected' 
'Device not available'; 
'Resource not available'; 
'Invalid block nuaber': 
'Device error ~ bad address or data on disk'; 
'Can"t find the specified subdirectory'; 
'Voluae not found'; 
'File not found'; 
'Directory full'; 
'Illegal access atteapted'; 
'File busy'; 

'Duplicate voluae error' 
Set Jrror_types ) 



PROCEDURE Set File types; 
BEBIN ■ " 

File type CO] 

File"type C2] 

File"type C4] 

File"type ihl 

File'type CO] 

File'type C10];= 

File'type C12] 



{ Sets the file types > 



= 'Unknown 'i 
» 'PascalCode' 
= 'Ascii '! 
is 'Binary ' 
= 'Picture ' 

BasicData ' 

SOSfile 



Fileltype C14]:= 'Datafile 



END; {"of PROCEDURE Setjile.types > 



File type CU i^ 
File'type C3] ;= 
File'type C5] ;* 
File'type C7] := 
File'type C9] := 
File'type CU];= 
File'type C13]:= 
File"type C15]:= 



'BadBlocks '; 
'Pascal Text'; 
'PascalData'; 
'FontData '; 
'BasicProq '; 
'NpText '; 
'Datafile '; 
'Directory ' 



PROCEDURE Trap 10 error; 
BEBIN ' 
IF aORESULT <> 0) THEN 
BEBIN 
Error := lORESULT: 

Error aessage ;« Error type CErrorl; 
CLOSE'(Infile); 
CLOSE (Device); 
EXIT (List SOS Directory) 
END ' ' 
END; { Of PROCEDURE Trap 10 error > 



{ If an error occurs, leave the unit } 
{ with an appropriate error aessage. } 



PROCEDURE Set Out device; 
VAR i: Counter; 



{ Sets the appropriate output file } 
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/// /// 



/// 



/// /// /// /// /// /// /// /// /// /// 



/// 



BE6IN 
IF (LEN6TH (Out Path) = 0) THEN 
BEfilN 
Error ;= 7; {An illegal Pathnaie } 
Error lessaqe := 'You lust supply a pathnaie!'; 
CLQSE'(Infile); 
CLOSE (Device); 
nil (List SOS Directory) 
END " ' 
ELSE 
BEGIN 
FOR i := 1 TO LEN6TH (Out Path) DO 
IF (Out Path [i] IN C'a\.'z'3) THEN 
Out Path [i] := CHR (ORD (Out Path Ci]) - 32); 
IF ((Oul Path <> '.CONSOLE') AND lOut Path <> 'ID) THEN 
IF ((Out Path <> '.PRINTER') AND (Out Path <> '.SPRINTER') AND 
(Out Path <> '.PPRINTER') AND (Out Path <> '§&')) THEN 
IF"(POS ('.TEH', Out Path) = O'THEN 
IF (LEN6TH (Out Patfi) < U) THEN 
Out Path := CffNCAT (Out Path, '.TEH'); 
{$IOCHECK- } " 

REWRITE (Device, Out Path); 
CLOSE (Device, LOCK)] 
Trap 10 error; 
REWRITE" (Device, Out path); 
{$IOCHECK+ } 

Trap 10 error 
END ■ " 
END; { Of PROCEDURE Set>t Jevice } 



PROCEDURE Set file info (nui: INTE6ER); { Bet the file inforiation > 
CONST offset = 4; " 

bytes per entry = 39; 
VAR i: Counfer;" 

loN.byte, first, teip: INTE6ER; 



BEGIN 
first := ORD (nui = 12); 
FOR i := first TO 12 DO 
BEGIN 
Ion byte := (bytes per entry t i) + offset; 
NITR Directory.Files [i3 DO 
BEGIN 
nOVELEFT (Block buf [Ion byte * 01, Len, 1); 
Nate := ' ': 

NOVELEFT (Block buf [lov byte * 11, Naae [U, IS); 
ten :- len. len; 
HOVELEFT (teip, Naie, 1); 
F type := Unknown; 

HUVELEFT (Block buf [Ion byte + 161, F type, 1); 
NOVELEFT (Block'buf Elon'byte + 17], Start blk, 7); 
HOVELEFT (Block'buf Clou "byte + 243, Create date, i); 
F Status ;= 0; " 

HffVELEFT (Block buf [Ion byte ♦ 303, F Status, 1); 
HOVELEFT (Block'buf Clow'byte + 313, NistB2, 8) 
END - - » » 

END 
END; { Of PROCEDURE Get file info ) 



PROCEDURE Open_Directory; { Open the directory for use ) 

PROCEDURE Check for valid directory; { Deteriine if it's a directory > 
BEGIN " ' 
{$IOCHECK~ } 

Count := BLOCKREAD (Infile, Block buf, 1); 
{$IOCHECK+ } 

Trap 10 error; { These are the 'signature bytes' } 

IF (iBlock buf [03 <> 0) OR { that should always be '0' It '39' } 
(Block 'buf [353 <> 39)) THEN { on an Apple /// SOS directory. } 
BEGIIil 
Error := 7; { Not a valid directory } 
Error lessage :~ 'Not a valid directory'; 
CLOSE'dnfile); 
CLOSE (Device); 
EXIT (List SOS Directory) 
END " " 
END; { Of PROCEDURE Check.for_valid.directory } 

BEGIN { Nain of Open Directory } 
{SIOCHECK- } 

RESET (Infile, Pathnaie); 
{$IOCHECK^ } 
Trap IO_error; 
Checi for valid directory 
END; { af PROCEDURE Openjirectory } 



PROCEDURE Get root info; ( Get the voluie inforiation } 
VAR teip: INTEGER;' 

BEGIN 
HOVELEFT (Block buf [03, Directory, 4); 
NITH Directory.Root DO 
BEGIN 
NOVELEFT (Block buf [43, Len, 1); 
Naie := ' ': ' 

HOVELEFT (Block.buf [53, Naie [13, 27); 
teip :- len. len; 
HOVELEFT (teip, Naie, 1); 
Vol := 0; 

HOVELEFT (Block buf [323, Vol, 1); 
HOVELEFT (Block'buf [333, Naste2, 10) 
END 
END; { Of PROCEDURE Get root info } 



PROCEDURE ShoN root info; { Mrite out the root (voluie) inforiation > 
BEGIN 
NITH Directory.Root DO 
BEGIN 
NRITE (CHR (clear vieiiport}); 
HRITE (Device, Naie, ' ('); 
MITH Create date DO 
MRITE (Device, CHR (lonth DIV 10+48), CHR (lonth HOD 10+48), V, 
CHR (day DIV 10M8), CHR (day HOD 10+48), '/', 
CHR (year DIV 10+48), CHR (year HOD 10+48), ' '): 
NITH Create tiie DO 
NRITE (Device, CHR (hour DIV 10+48), CHR (hour HOD 10+48), ':', 
CHR (linute DIV 10+48), CHR (linute HOD 10+48)); 
URITELN (Device, ') ', 'Voluie ♦', Vol); 
NRITELN (Device) 
END 
END; { Of PROCEDURE ShoN.root .info } 

PROCEDURE ShoN disk info; FORHARD; { Declare these now, so we can use ) 
PROCEDURE Do if; FORWARD; ( thei in 'ShoM file info' in case ) 

{ the user presses 'ESCAPE' to exit > 

PROCEDURE New page (Hessage: STRING); 
VAR Ch: CHAR;' 

{ Proipts the user to press a key for lore files, or to end ) 
BEGIN 

60T0XY (0. 23); 

WRITE (CHR (inverse), Hessage, CHR (norial)); 

READ (KEYBOARD, Ch): 

WRITE (CHR (clear viewport)) 
END; { Of PROCEDURE'New page } 



PROCEDURE Show file info (nui: INTEGER); 
VAR i. Teip counter: Counter; 

big int.' INTEGER [83; ( Use LONG INTEGERS in printing out the nuiber ) 

the file o 



PROCEDURE Do header; 
BEGIN 



{ of bytes (EOF) that 
{ Write out the title display } 
Blks File Naie '); 



{ Write out the files info. } 

out the null 
occupies. } 



WRITE (Device, ' Type 

WRITELN (Device, 'Created Tiie Hodified Tiie Phys' EOF'); 
Line count := Line count * 5 
END; fOf PROCEDURE Do.header } 
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/// /// /// /// /// /// /// /// /// /////////////// 



FUNCTION Keypress: BOOLEAN; 
VAR CharCountj INTEBER; 



{ The standard function; tests to see } 
{ if a key has been pressed. ) 



BE6IN 

CharCount ;= 0; 

UNITSTATUS (1, CharCount, 21); 

Keypress ;= CharCount <> 
END; { Of FUNCTION Keypress } 



PROCEDURE Check Keypress; { Tests to see if a key has been pressed. } 
VAR Ch! CHAR; ' C If so, in the case it's an 'ESCAPE* the > 
{ disk info is shown. OtherNise, it waits } 
BE6IN { until the user presses another key to ) 

IF Keypress THEN { continue the listing. } 

BEfilN 
READ (KEYBOARD, Ch): 
IF (Ch = CHR (27)) THEN 
BESIN 
Show disk info; 
EXIT" (Do It) 
END 
ELSE 
READ (KEYBOARD, Ch) 
END 
END; { Of PROCEDURE Check tepress ) 

PROCEDURE Check console; C Checks for various options ) 
BE6IN 
IF ((Out Path <> '.CONSOLE') AND (Out Path <> 'II')) THIN 

HRITE ('.') 
ELSE 
IF (Line count - Lines on window) THEN 
BEBIH" ' " 
New page ('Press any key for lore'); 
Line count :- 2 { The end of a page - so lake a new one. } 
END " 
END; { Of PROCEDURE Check.console } 

PROCEDURE PrintLine (i: Counter); { Nrites out one parsed file line > 

{ Nrite out the nuiber of } 
{ blocks used by the file > 



PROCEDURE Nrite blks nui (nui: INTE6ER); 

VAR teip: INTE6ER; ~ 

BE6IN 

teip I' nue; 

HRITE (Device, CHR (teip DIV 10000H8)); teip :» teip HOD 10000; 

WRITE (Device, CHR (teip DIV 1000-I-48)); teip :^ teip HOD 1000; 

HRITE (Device, CHR (teip DIV 100H8)); teip :- teip NOD 100: 

WRITE (Device. CHR (teip DIV 10H8), CHR (teip NOD 10M8), ' ') 
END; ( Of PROCEDURE Nrite.blks.nui ) 

PROCEDWE Dojate^recs (Dater Oate.rec; Tiies Tiie.rec); 

BESIN 
WITH Date DO 



{ Mrite out one parsed date record in ) 
{ the fori Honth/Day/Year Hour:Ninute ) 



HRITE (Device, CHR (lonth DIV 10M8), CHR (lonth HOD 10-^48}, '/', 
CHR (day DIV 10M8), CHR (day HOD 10+48). '/', 
CHR (year DIV 10+48), CHR (year HOD 10+48), ' '); 
HITH Tiie DO 
NRITE (Device, CHR (hour DIV 10+48), CHR (hour HOD 10+48), '.*', 
CHR (linute DIV 10+48). CHR (linute HOD 10+48), ' M 
END; { Of PROCEDURE Do_date_recs } 

PROCEDWE Do.blocks (F.type: Filekind; Mii: INTEBER); 

{ Nrite out the nuiber of blocks that the file itself takes } 
{ up. This does not take into account the header blocks. ) 



BEBIN 
IF (F type = Sos directory) THEN 

ttrile blks nui (Nui) 
ELSE ' " 
IF (Nui = 1) THEN 

Nrite blks nui (Nui) 
ELSE " ■ 
IF (Nui <= 257) THEN 

Write blks nui (Nui - 1) 
ELSE " ' 
Write blks nui (Nui - ROUND (Nui / 257 + 0.5) 
END; { Of PROCEDURE Do blocks ) 



{ The file is locked ) 



BEBIN ( Hain of PrintLine ) 
WITH Directory.Files Cil DO 
BEBIN 
IF (F status < 128) THEN 

WRITE (Device, '$') 
ELSE 

WRITE (Device, ' '); 
WRITE (Device, File type CORD (F type)], ' '); 
Do blocks (F type, iilui blks); ~ 
WRITE (Device, Naie, ''': (16 - Len.Len)); 
Do_date_recs (Create date, Create_tiie); 
Do'date'recs (Hod dale, Hod tiie)] 
Wrfte bfks nui (Nui blks); " 

WRITElN (Divice, Nui bytes CO] + Nui bytes CU t big int + 
Nui bytes ill t big int t big int) 
END ■ " " 

END; { Of PROCEDURE PrintLine ) 

BEBIN { HAIN of Show file info ) 
big int:= 256; 
i := ORD (nui= 12); 
IF (i - 1) THEN { If we get here, it's the first (root) block } 

Do header; 
REPEAT { Until the block is eipty or there ) 

WITH Directory.Files Ci] DO { are no lore files to list. ) 
IF (Len.Typ <> 0) THEN 
BEBIN ( If the file slot isn't eipty, print it. > 

PrintLine (i); 

File.count := File.count + 1; 
Line count ;= Line'count + I; 

ChecF console; ( Handles end of paae and output not to '.CONSOLE' ) 
Check Keypress ( Check to see if tne user wants to } 
END; { teiporarily stop the listing or leave. } 
i :« i + 1 
UNTIL ((i = 13) OR (File count = Directory. Root. Files on dir)) 
END; { Of PROCEDURE Show.file.info } " " 

PROCEDURE Show disk info; ( Show the voluie inforiation ) 
VAR V Naie: STl^INB;' 

Tot.blks, Fre.blks, Err: INTEBER; 

BEBIN 
WRITELN (Device); 
WITH Directory.Root DO 
BEBIN 
WRITE (Device, File count, ' Files listed, '); 
WRITELN (Device, Files on dir, ' Files on this directory'); 
IF (Len.Typ « IS) THEN' '{ If it's a root voluM, get ) 
BEBIN { the root voluie inforiation. > 

SOS Voluie (Pathnaie, V Naie, Tot blks, Fre blks, Err); 
IF lErr = 0) THEN 
BEBIN 
WRITE (Device, 'Free Blocks: ', Fre Blks): 
WRITE (Device, ' Blocks Used: ', (Tot biles - Fre Blks)); 
WRITELN (Device, ' Total Blocks: ', Tot blks) " 
END 
ELSE 
WRITELN (Device, Blks on disk, ' Total blocks on this disk') 
END » - - » 

END; 

Program Hstir^g continued on page 39 
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flsscmblinQ (ON) the /// 



by Martin Nichols 



Last month I presented some assembly lansuase functions that 
made it easier for your Business Basic and Pascal programs to 
tell if the ENTER key or a key on the numeric keypad had been 
pressed. One of the functions also returned the second byte of 
keyboard data. Included was a Basic program that enabled the 
user to tell the status of all the bits of the second byte. 

That program was not too easy to understand, so I am going to 
implement what that program did as a new group of assembly 
language routines. Just like last month, these routines can be 
INVOKE'd from Basic and Dinked from Pascal. 

Simply put, we are going to make assembly language functions that 
will tell the user if certain keys (Closed Apple, Open Apple, Alpha 
Lock, Control and Shift) are being pressed. Program listings #1 and 
#2 show how easy these new functions are to use from both Basic 
and Pascal. 

To use these functions, very simple Basic statements like 'Pressed = 
EXFN%. AlphaLock' will return a one in the variable 'Pressed' if the 
Alpha Lock key is being pressed and a zero if it's not. Program 
listing #4 is the documentation for these assembly language func- 
tions. It gives a fair amount of information on how to use these 
routines. 

Program listing #3 are the assembly language routines that make 
these tricks very easy. As you can see, there are eight functions in 
this module. One for each of the bits of the second byte of 
keyboard data. Each one is very simple. First they load the accumu- 
lator with the appropriate mask for the bit to be tested, and then 
use the 'BIT' command to compare the mask value with the second 
byte of keyboard data. 

I've received some mail saying that you can already do some of 
these functions from Basic and Pascal with no assembly language 
routines, other than the ones that are supplied with the system. This 
is true, but they dre much harder to read and understand. 

Part of what the Apple /// does so well is to allow the user to 
expand the languages of the machine with easily invokable or 
linkable modules. I think that people would much rather use the 
one line statement 'Pressed = EXFN%. AlphaLock' over a twenty or 
so line subroutine to test if the Alpha Lock key is being pressed. 

To use these routines in your programs, use the Pascal editor to 
enter the assembly language routines in listing #3. Assemble it and 
name it 'KBDFLAG'. The file that the assembler creates will contain 
the useable assembly language functions, and its name will be 
'KBDFLAG.CODE'. To show that this can be used as an invokable 
module, use the filer to change its name to 'KBDFLAG.INV. 

If you want to test these routines using Pascal, type in and compile 
program listing #2. Then, use the linker to link them into the Pascal 
host program. From Basic, just boot a Basic disk and type in 
program listing #1 . Make sure the assembly language routines are 
available and run it. 



the special keys and the program will tell you what you've pressed! 
If you have any questions you can refer to the documentation 
program (Listing ^4). 

Next time I will show you how to 'lock up' and 'un-lock' the RESET 
key in addition to a way to have your/// reboot without having to 
press'CONTROLRESET'. Alsol will include a procedure that allows 
you to cut your Apple ///s' speed in half. This last one is for those 
of you who feel that life is going by too fast. 

Until then, write and tell me what you want your /// to be able to 
do. I will try my best to accomodate you. /// 



Assembling (ON) the ///: 
Program Listing #1 



REH mtuuutmmtmtutnmmtmumtmtmmmummtm 

\ REH I 

2 REH t Key-Things: KbdFlaq invokable lodule ! Copyright 1982, 1983 

3 REH t (Part 2) BASIC test prograi. ! ON THREE 

4 REH t I February-Harch, 1983 

5 REH I by Hartin Nichols 

6 REH I 

7 REH I This prograi iiill test the state of all the bits of the second 

8 REH t byte of keyboard data. Here's the easy way to tell if the Alpha 

9 REH t lock, control, shift, open apple, closed apple anil tore ire being 

10 REH I pressed. Through very siiple stateients like 'keyZ=EXFNI.Shift' 
U REH I you can deteriine a wealth of inforiation that your prograas can 

12 REH t use to lake life a little easier for the user. 

13 REH t 

14 REH luitiutiitiitittittiiuiimimimimimtmiimmttmttttti 

15 IMVOKE'KBDFLAS.IHVjSOTO 50 

20 PRINT CHRIU7fSNitch);:PRlNT Key. type! (Niui):Nui»Nui^i: RETURN 

50 TEXT:HOHE:ON KBD GOTO 200 

60 VP0S=10sPRINT USIN6'56C"|'<- PRESS CONTROl-E TO EXIT ->• 

70 Key. type! (U="Special key (Keypad, Arrows, Space, Escape and Tab keys)" 

:Key.typel(2)="Keyboard is on':Key.typel(3)="Closed Apple" 

80 Key.type$(4)="0pen Apple":Key.type$(5)="Alpha lock": Key. type! (6)= 

•Control":Key.typell7)="Shift':Key.type$<8)=-Any key" 

90 Nui=l:VPOS=I 

100 Switch^ E](FNZ.Special:60SUB 20 
110 Switch:^ EXFNI.Kybd0n:60SUB 20 

120 Snitch:^ EIFNX.ClosedApple:SOSUB 20 
130 Switch^ EXFNZ.0penApple:60SUB 20 

140 Switch^ EXFNZ.AlphaLock:60SUB 20 
150 Switchs EXFNZ. Control :60SUB 20 
160 Switch^^ EXFNZ. Shi ft: 60SUB 20 
170 Switch^ EXFNZ.Anykey:60SUB 20 
180 SOTO 90 

200 IF KBD=5 THEN N0RHAL:VP0S=12jENB 
210 ON KBD GOTO 200 
220 RETURN 



Once you have the prosram running (Basic or Pascal), press any of 
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/// /// 



/// 



Assembling (ON) the ///: 
Program Listing #2 



PR06RAH Pascal JbdfUg^test J 



mtmmtmmmmmmmummmmummnmnumnmmti 

I Key-Things (Part2): Pascal test prograi ! Copyright 1982, 1983 by I 

J j OH THREE I 

t by Martin Nichols I February-Harch, 1983 I 

I 

t This prograi Mill check the status of the keyboard special keys and 

I lore using the external assembly language routines that are declared 

t below. After coipiling this prograi, use the L) inker to link together 

t the asseibly language routines to this host prograi. 

I 

I When you run this prograi, see hoM easy it is to deteriine the state 

t of all the lodifier keys by pressing thei. 

t 

mmmtummmmimttmmmmtmmmmmummmmm 



CONST Ctrl.E = 5; 



{ Provide a leans for the user to exit the prograi. } 



VAR Nui: INTESER; 

Key.type: ARRAY [1..8] OF STRINB; 
Ch: CHAR; 



FUNCTION Special: 1NTE6ER; EITERNM.; ( These are the routines that you } 
FUNCTION Kybdon: INTE6ER; EXTERNAL; { can use to very easily deteriine ) 
FUNCTION Closedapple: INTEGER; EXTERNAL; ( the state of all the bits of the } 



FUNCTION Openapple: INTEBER; EXTERNAL; 
FUNCTION Alphalock: INTEGER; EXTERNAL; 
FUNCTION Control: INTE6ER; EXTERNAL; 
FUNCTION Shift: 1NTE6ER; EXTERNAL; 
FUNCTION Anykey: INTEBER; EXTERNAL; 



{ second byte of keyboard data. } 



{ Tests to see if a key has been pressed. } 



FUNCTION Keypress: BOOLEAN; 
VAR Charcount: INTEBER; 

BEGIN 

Charcount := 0; 

UNITSTATUS (1, Charcount, 21); 

Keypress := Charcount <> 
END; { Of FUNCTION Keypress } 



PROCEDURE Initialize; { Set up the prograi variables. } 

BEBIN 

Key_type [11 := 'Special key (Keypad, Arrows, Space, Escape and Tab keys)'; 

Key_type 123 := 'Keyboard is on'; 

Key_type [33 := 'Closed Apple'; 

Key_type [43 := 'Open Apple'; 

Key.type [53 := 'Alpha lock'; 

Keyjype [63 := 'Control'; 



Key.type [73 := 'Shift'; 
Keyjype [83 := 'Any key'; 
Nui := i; 
WRITE iCHR (28)) 
END; { Of PROCEDURE Initialize 1 



{ Clear the screen for use. ) 



PROCEDURE Display (Switch: INTEGER); { Show the line in either inverse } 
BEBIN ( or norial, depending on the state ) 

WRITE (CHR (17 ♦ Switch)); { of the variable 'Switch'. > 

WRITELN (Key.type [Nui3); 

Nui := Nui ^ 1 
END; { Of PROCEDURE Display > 



{ Perfori the test of the second byte of keyboard data. } 



PROCEDURE Test; 
BEBIN 

Nui := 1; 

Display (Special); 

Display (Kybdon); 

Display (Closedapple); 

Display (Openapple); 

Display (Alphalock); 

Display (Control); 

Display (Shift); 

Display (Anykey); 

GQTOXY (0, 0) 
END; { Of PROCEDURE Test } 



PROCEDURE Exit.Proipt; 
BEGIN 

GOTOXY (13, 9); 

WRITELN ('<- PRESS CONTROL-E TO EXIT ->'); 

GOTOXY (0, 0) 
END; { Of PROCEDURE Exit.Proipt } 



BEGIN { Hain Prograi } 
Initialize; 
Exit.Proipt; 
REPEAT 
IF Keypress THEN 

READ (KEYBOARD, Ch); 
Test 
UNTIL (ORD (Ch) = Ctrl.E) 
END. { Of PR06RAH Pascal .kbdflag.test ) 



{ Bo back to the top of the screen for lore. ) 



{ Tell the user how to exit the prograi. 1 
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/// /// 



Assembling (ON) the ///: 
Program Listing #3 



Hmimmmmmtmmnmmnmmmtmmmmmmmmmt 
I 

Key-Things iPart2)j KbdFlag assetbly 1 Copyright 1982, 1983 by 
language routines. ! ON THREE 



February-March, 1983 



by Hartin Nichols 



t 

I 
t 
I 
I 
t 
I 
t 
I 
I 
I 
I 
I 
I 
I 
I 

ittnittmuttittttttuutttttttitttttmtuttututtttttituttttuttutut 



These assembly language routines Mill enable your Basic or Pascal 
prograis to easily deteriine the status of all the bits of the second 
byte of keyboard data. You Hill be able to tell when the user is 
pressing the shift key, when they are pressing any of the other lodifier 
keys and luch lore. 

To use in you Basic prograis, asseible this routine using the Pascal 
asseibler, and then invoke it as you Mould any other invokable lodule. 

For use in Pascal, declare each of these routines EHERNAL FUNCTIONS 
and use the linker to link thee into your Pascal host prograi. 



; restore environient 

; restore status (including interrupts) 

;6ive an answer 

iCoie back froi non SOS-land 



.HACRO Pop 

PLA 

STA 11 

PIA 

STA l\H 

.ENDH 

.HACRO Push 

LBA liH 

PHA 

IDA XI 

PHA 

.ENDH 

.HACRO Open 

Pop Return 

PLA 

PLA 

PLA 

PLA 

LDA 

STA 

STA 

PHP 

SEI 

LBA 

STA 

LBA 

STA 

.ENDH 



too 

Result 
Result^l 



Envrit 
Env 
#73 
Envrit 



;Pull a Nord froi the stack 



.HACRO Close 

LBA Env 

STA Envrit 

PLP 

Push Result 

Push Return 

.ENDH 

Return .EOU 

Result .EQU 2 

Env .E8U 4 

Kbdflag .EQU 0C008 

Envrit .EBU OFFBF 



5 - Function Special - 

> 

;lf a special key (See pages 135 and 165 of the Standard Bevice Brivers Hanual) 
;Mhich consists of Escape, Tab, Space, the cursor control keys, and keys on the 
;nuieric keypad, but not the 'RETURN'!!! key, is pressed, the BASIC stateient 
rintl = EXFNX.Special' will return a value of 1 in the variable 'intZ'. If the 
;key just pressed Mas not a so-called special key, the function Mill return a 
;in the variable 'intV, 

.FUNC Special, 

Open 



;Push it back on^ 



LBA 
BIT 
BE8 

LBA 
STA 

Bone Close 
RTS 



180 

Kbdflag 

Bone 

101 
Result 



; Begin test to see if a special key Mas pressed 



;If Me get here it's a special key 
; Store the character 



;Tiie to go hoie 



{Discard 4 bytes stack bias 
;(for .FUNC only) 



jZero the address 'Result' because 
;you never knoN Nhat it lay contain. 

;save status, then disable interrupts 

;save environient 

;Use a neN environient register 

;Do this to get at the 'COOO' I/O space. 



- Function KybdOn - 

If the Keyboard is on (See page 165 of the Standard Bevice Drivers Hanual) 
the BASIC stateient 'intZ » EXFNZ.KybdOn' Mill return a value of 1 in the 
variable 'intZ'. If the keyboard is off, the function Mill return a in 
the variable 'intZ'. 



Bone 



.FUNC 


KybdOn, 




Open 






LBA 
BIT 
BEQ 


140 

Kbdflag 

Bone 


;Begin test to see if the keyboard 


LBA 
STA 


101 
Result 


;If Me get here the keyboard is on 
fSave the ansMer 


Close 
RTS 




;Back Me go! 
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- Function ClosedApple - 

If the Closed Apple key (See page 165 of the Standard Device Drivers Nanual) 
is being pressed down in conjunction Nith another key, the BASIC statement 
'intX = EXFNZ. ClosedApple' will return a value of 1 in the variable 'intZ\ 
If it is not being pressed, the function will return a 0. 



; Begin test to see if the Closed Apple key is 
; being pressed. 



Done 



IDA 
STA 

Close 
RTS 



iOl ;If ite get here the Alpha Lock key is pressed 
Result ;Save the answer 

;Back we go! 



.FUNC 


ClosedApF 


le,0 


Open 






IDA 
BIT 
BNE 


120 

Kbdflag 

Done 




IDA 
STA 


101 
Result 




Close 
RTS 







- Function Control - 

If the Control key (See page 165 of the Standard Device Drivers Hanual) 
is being pressed down, the BASIC stateient MntX - E](FNX. Control' will 
return a value of 1 in the variable 'intZ'. If it is not being pressed, 
the function will return a 0. 



;If we get here the test is true 
I Save the answer 



Done Close ,*Back we go! 



- Function OpenApple - 

If the Open Apple key (See page 165 of the Standard Device Drivers Hanual) 
is being pressed down, the BASIC stateient 'intZ ~ EXFNZ. OpenApple' will 
return a value of 1 in the variable 'intZ'. If the Open Apple key is not 
being pressed, the function will return a in the variable 'intZ'. 



{Begin test to see if the Open Apple key is 
I begin pressed. 



;If we get here the Open Apple key is pressed 
;Save the answer 

Done Close ;Back we go! 



- Function AlphaLock - 

If the Alpha Lock key (See page 165 of the Standard Device Drivers Hanual) 
is being pressed down, the BASIC stateient 'intZ ' EZFNZ. AlphaLock' will 
return a value of 1 in the variable 'intZ'. If it is not being pressed, 
the function will return a 0. 

.FUNC AlphaLock,0 

Open 



Done 



.FUNC 


Control, 


Open 




LDA 


104 


BIT 


Kbdflag 


BNE 


Done 


LDA 


101 


STA 


Result 


Close 




RTS 





{Begin test to see if the Control key is 
; being pressed. 



;If we get here the Control key is pressed 
;Save the answer 



.FUNC 


OpenApple,0 


Open 




LDA 
BIT 
BNE 


110 

Kbdflag 

Done 


LDA 
STA 


101 
Result 


Close 
RTS 





{Back we go! 



- Function Shift - 



If the Shift key (See page 165 of the Standard Device Drivers Nanual) 
is being pressed down in conjunction with another key, the BASIC stateient 
'intZ = EXFNZ.Shift' will return a value of 1 in the variable 'intZ'. 
If it is not being pressed, the function will return a 0. 



Done 



LDA 108 
BIT Kbdflag 
BNE Done 



{Begin test to see if the Alpha Lock key is 
{being pressed. 



.FUNC 


Shift,0 




Open 






LDA 
BIT 
BEQ 


102 

Kbdflag 

Done 


{Begin test to see if the Shift key is 
{being pressed. 


LDA 
STA 


101 
Result 


{If we get here the Shift key is being 
{Save the answer 


Close 
RTS 




{Back we go! 




- 


Function Anykey - 



If Any key (See page 165 of the Standard Device Drivers Hanual) 
is being pressed down, the BASIC stateient 'intZ - EXFNZ. Anykey' will 
return a value of 1 in the variable 'intZ'. If it is not being pressed, 
the function will return a 0. 

.FUNC Anykey, 
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Open 

IDA lOi 

BIT Kbdflaq 

BEO Bone 



Done 



LDA 
STA 

Close 
RTS 

.END 



101 
Result 



;Begin test to see ii any key is pressed. 



;H Me get here the test is true 
;Save the answer 

;Back we go! 



;0I Asseibly 



Assembling (ON) the ///: 
Program Listing #4 



10 REH uiuiuuttunnntttttttttitnittttntttttituitttiuttiuutut 

20 REH t 

30 REH I Kbdflag Invokable Hodule Docuientation 

40 REH t 

50 REH I (C) Copyright 1982, 1983 by ON THREE 

&0 REH t 

70 REH itimttttttttttttuttiuituttuitttutttttitttttttttutttutnttr 

80 • TElT:titlel=CHR$(15)+' KBDFLA6 INVOKABLE HODULE •zSOSUB 300 

90 PRINTsFRINT" Before any Invokable Hodule can be used, it lust be 

loaded into the'sPRINT'systei by the folloNing Coiiand Foriat:' 
100 PRINT: PRINT') INVOKE KBDFLA6.INV: PRINT: PRINT'where KBDFU6.INV can be 

the naie of this or another Invokable Hodule. ":PRINT:6QSUB 200 

110 title$=CHR$U5)+- KBDFLAB INVOKABLE HODULE •:60SUB 300 

120 PRINT:PRINT TAB(8); "Select docuientation on: •:PRINT 

130 PRINT TAB(20);M Reading the Special key status": PR I NT TAB(20);"2 

Reading the state of the keyboard' 
140 PRINT TABC20);'3 Reading the state of the open Apple key"-:PRINT 

TAB (20); '4 Reading the state of the closed Apple key' 
142 PRINT TAB(20};'5 Reading the state of the Alpha Lock key':PRINT 

TAB (20) I '6 Reading the state of the Control key' 
144 PRINT TAB(20);'7 Reading the state of the Shift key':PRINT TAB(20); 

'8 Reading the Any key status' 
146 PRINT TAB(20);'9 End':PRINT 
150 PRINT TAB(8)|"Nhich option '|:INPUT alsx=C0NVCLEFT$(al,2))5 

IF x<0 THEN x«0 
160 ON X GOTO 1000,2000,3000,4000,5000,6000,7000,8000,180 
170 PRINT TAB(8) J 'Please enter 1, 2, 3, 4, 5, 6, 7, 8, or 9':VP0S= 

VP0S-2:80T0 150 
180 H0HE:END 

200 VP0S=24:PRINT USIN6'76c'; 'Press any key to Continue. ';:6ET a*:RETURN 
300 PRINT CHRI(14):H0HEjPR1HT USINB'76c'|titlel!PRINT:RETURN 
400 PRINT:PRINT TAB(5)'The Coiiand Foriat is:':PRINT 
410 PRINT'} keyZ^EXFNZ. ';funcnaae$: PRINT 
420 PRINT TAB(5)'This coMand should norially be used right after a 

keyboard read such' 
430 PRINT'as a GET or INPUT froi BASIC or a READ or READLN froi Pascal. 

It can also be' 
440 PRINT'used froi Pascal iith the following stateient;': PRINT 
450 PRINT'FUNCTION ';funcnaie$;':INTESER; EXTERNAL;": PRINT 



460 PRINT'After being defined in your Pascal prograi it can be called 

just as any other" 
470 PRINT'f unction. Reieiber it returns an INTEBER value so you can't 

assign it to a non-' 
480 PRINT'integer type variable with out converting it first. Froi 

Pascal you lust also" 
490 PRINT'reietber to Dink before you can eXecute the file.":RETURN 
1000 REH — Special key status 
1010 titlBl="- Special key -•:60SUB 300iREH Page 1 
1020 PRINT TAB(5)"The SPECIAL Function returns a value of 1 if the 

last key pressed was a' 
1030 PRINT'special key. A special key is defined on pages 47-49 and 

pages 135-137 in the" 
1040 PRINT"Standard Device Drivers Hanual. Nith the exception of the 

RETURN key, whenever" 
1050 PRINT'a special key is pressed this function will return a 1. If 

the last key pressed" 
1060 PRINT'was not a special key, this function will return a value of 0." 
1070 funcnaiel="Special":60SUB 400:60SUB 200:6QSUB 300:REH Page 2 
1100 PRINT TAB(5);"You can also use this function frot the Iiiediate 

Execution «ode of BASIC 
1110 PRINT'by entering the following statements:": PRINT 
1120 PRINT')keyX=EXFNX.SpBcial: PRINT keyZ":PRINT 
1130 PRINT TAB(5);"ril bet you entered the above line by pressing 

RETURN. If you did the" 
1140 PRINT"5creen will respond with:":PRINT 
1150 PRINT')0':PRINT 
1160 PRINT TAB<5);"It returned a zero because the last key pressed 

(RETURN) was not one of 
1170 PRINT'the special keys. Now try this! Enter the line again, but 

instead of pressing" 
1180 PRINT'RETURN, hit the ENTER key on the nuteric keypad. You should 

now be greeted with:" 
1190 PRINT") l':PRINT 
1200 PRINT'because the last key pressed (ENTER) was on the nuieric 

keypad and thus one" 
1210 PRINT"of the special keys." 

1999 60SU6 200:60T0 110:REH Bo back to lenu 

2000 REH — Keyboard state 

2010 title$="~ Keyboard state ~":B0SUB 300:REH Page 1 

2020 PRINT TABI5)|"The KYBDON Function returns a value of 1 if the 

keyboard is on. I will" 
2030 PRINT'adiit it's an aliost useless function but it is included 

to provide a lethod of" 
2040 PRINT"reading the status of all the bits in the second byte of 

keyboard data. If the" 
2050 PRINT"keyboard is ever off (call le if yours ever does it) the 

function will return a" 
2060 PRINT"value of 0." 
2070 funcnaie$-"KybdOn":BOSUB 400 

2999 BOSUB 200: GOTO 110: REH Go back to tenu 

3000 REH — Open Apple 

3010 title*="- Open Apple -":BOSUB 300:REH Page 1 
3020 PRINT TAB(5)j"The OPENAPPLE Function returns a value of 1 if the 
last key pressed was" 
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3040 PRINT'the Open Apple key. If the last key pressed itas not the 

Open Apple key it niir 
3050 PRINT'return a value of 0. This function nill only return a value 

of i for the tite" 
3060 PRINT'that the key is being pressed, When the Open Apple key is 

released the function* 
3070 PRINfiiill return a value of O.'iPRINT 
3080 PRINT TAB(5)5'The Coiiand Foriat isi'sPRINT 
3090 PRINT")keyMXFHZ.OpenApple":PRINT 
3100 PRINT TAB(5};'This couand does not have to be used right after a 

keyboard read but it" 
3110 PRINT'can be used directly to see if the key has been pressed. It 

can also be used' 
3120 PRINT'froi Pascal nith the folloninq statement. ': PRINT 
3130 funcnaie$-'OpenApple':BOSUB 450 

3999 60SUB 200:60T0 110:REN Bo back to lenu 

4000 REH — Closed Apple 

4010 title$="- Closed Apple -'jBOSUB SOOsREH Page 1 

4020 PRINT TAB(5)j'The CLOSEDAPPLE Function returns a value of 1 if 

the last key pressed Mas' 
4030 PRINT'pressed in conjunction nith the Closed Apple key. If you 

press the letter 'A',' 
4040 PRINT'and at the saie tiie press the Closed Apple key, this 

function nill return a 1." 
4050 PRINT'If the last key pressed was not pressed at the saie tiie 

as the Closed Apple key"; 
4060 PRINT"tor after) the function will return a value of 0." 
4070 Funcnaiel-'ClosedApple'.'BOSUB 400:60SUB 200:60SUB 300:RER Page 2 
4100 PRINT TAB(S); "After this function returns a 1 it Mill continue 

to return a 1 each tiie" 
4110 PRINT'it is called until another key is pressed that is not 

pressed at the saie tiie' 
4120 PRINT"the Closed Apple key is being held. In other words, this 

function will retain on'i 
4130 PRINT"until it is explicitly turned off.'iPRINT 
4140 PRINT TAB<5) J "Unlike other functions that vb 'on' only as long 

as their specific key is* 
4150 PRINT'being pressed, this function reiains on until another key 

turns it off. The keys*j 
4160 PRINT'that will turn it off are any of the regular ones that are 

not being held at the"; 
4170 PRINT"saie tiie as the Closed Apple key.* 

4999 BOSUB 200:60T0 110:REH Bo back to lenu 

5000 REH — Alpha lock 

5010 title$=*- Alpha Lock -".•BOSUB 300:REH Page I 

5020 PRINT TAB (5); 'The AlPHALOCK Function returns a value of 1 if the 

Alpha lock key is being" 
5030 PRINT'pressed. If the Alpha lock key is not being pressed the 

function will return a" 
5040 PRINT"value of 0.":PRINT 
5050 PRINT TAB(5};'The Coiiand Foriat is.-'sPRINT 
5060 PRINT')keyX=EXFNl.Alphalock':PRINT 
5070 PRINT TAB(5};"This function should be used directly, without 

using a BET or INPUT first." 
5080 PRINT'By calling this function you will be able to easily 

deteriine the state of the* 



5090 PRINT'Alpha lock key. It can also be used froi Pascal with 

the following stateient:":PRINT 
5100 funcnaiei-'Alphalock":60SUB 450 

5999 BOSUB 200:60TO UO:REH Bo back to lenu 

6000 REH — Control key 

6010 title$="- Control key -":BOSUB 300:REH Page 1 

6020 PRINT TAB(5);"The CONTROl Function returns a value of 1 if the 

Control key is pressed." 
6030 PRlNT"If the Control key is not being pressed the function will 

return a value of 0." 
6040 PRINT'This function will only return a 1 as long as the key is 

being pressed, as soon' 
6050 PRINT'as the key is released this function will return a 0.":PRINT 
6060 PRINT TA8(5);"The Coiiand Foriat is.-'.-PRINT 
6070 PRINT")keyZ=EXFNZ.Contror:PRINT 
6080 PRINT TAB(5};"This function can be used directly, without using a 

BET or INPUT first." 
6090 PRINT'By calling this function you will be able to easily deteriine 

the state of the' 
6100 PRINT'Control key. It can also be used froi Pascal with the 

following stateients'i PRINT 
6110 funcnaie$="Contror: BOSUB 450 

6999 BOSUB 200:60T0 110: REN Bo back to lenu 

7000 REH -- Shift key 

7010 titlef="- Shift key -"jBOSUB 300:REH Page 1 

7020 PRINT TABI5)j"The SHIFT Function returns a value of 1 if the last 

key pressed was pressed* 
7030 PRINT'in conjunction with the Shift key. This function will return 

a value of 1 until' 
7040 PRINT'another key is pressed that was not pressed at the saie tiie 

as the Shift key." 
7050 funcnaie$="Shift":BOSUB 400 

7999 BOSUB 200:B0T0 110: REN Bo back to lenu 

8000 REH — Any key 

8010 title$="- Any key -":BOSUB 300:REH Page 1 

8020 PRINT TAB<5);"The ANYKEY Function will return the value 1 if a key 

was pressed directly" 
8030 PRINT"before this function was called. Possible uses include testing 

to see if a key* 
8040 PRINT"was pressed during the execution of a prograi. It's aliost 

like the BASIC ON KBD"; 
8050 PRINT"stateient, in that it will tell if a key was pressed during 

prograi execution." 
8060 funcnaie$-"Anyi(ey":60SUB 400 
8999 BOSUB 200:60T0 110:REH Bo back to lenu 
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The products outlined below have been received by ON THREE 
for the purpose of review. Some have been reviewed In the 
past and many will be reviewed in the future. The products have all 
been siven the ON THREE 'stamp of approval'. This is only an 
indication that a product works as advertised and Is not an endor- 
sement of the product by ON THREE. 

PFS: FILE & REPORT 

With PFS: File you can create a file, search and update any item or 
Sroup of items in the file, and print sorted information. Information 
management at its best, these programs are extremely easy to use. 

All PFS products are designed so that a novice can master them in 
less than an hour. Reviewed in the January issue of ON THREE, these 
programs received an A- and a B- respectively. 

Available from most authorized Apple dealers, these programs are 
made by Software Publishing Corporation and are priced at $175 
and $125 respectively, for the Apple ///. 

Software Publishing Corporation, 1901 Landings Drive, Mountain 
View, California 94043. (415) 962-8910. 

QUICK & EASY DATA MASTER 

Quick & Easy Data Master is a program that creates custom 
applications software and report forms designed to your specifi- 
cations. This package creates an unprotected Business Basic data 
base program as per your specifications. 

The ideal data base program Is one that you can design exactly the 
way you want it: prompts, edits, error messages, headers, titles, 
computed data. Interactive files, report forms, etc. to your specifi- 
cations. You design it and Quick & Easy will create it for you. 

Intended for the more serious computer user who knows how to 
program In Basic, this package Is not ver/ hard to use, but it does 
require some thought. Sold by Advanced Software Technology, 
Inc., It Is priced at $69.95. To be reviewed In the April-May Issue. 

Advanced Software Technology, Inc., 7899 Mastin Drive, Overland 
Park, Kansas 66204. (913) 648-4442. 

CRITICAL PATH SCHEDULING 

If you are involved In project management and tired of the hassels 
of project scheduling, the Critical Path Scheduling System is for 
you! It Is a management tool for defining and analyzing the overall 
concepts of a project and provides a powerful method for sched- 
uling the many tasks necessar/ to complete the project ON TIME 
AT THE LOWEST POSSIBLE COST. 

Armed with the information that this system provides, the manager 
is better prepared to make decisions regarding the impact any task 
will have on the project and permits him to be Instrumental In 
guiding the project rather than just monitoring its progress. 



This is a ver/ 'User Friendly' system, and it has an excellent tutorial 
/user manual. Comprehensive reports make a manager's life a lot 
easier. Developed by Great Divide Software, It has a suggested 
retail price of $495. To be reviewed In the April-May Issue. 

GL'PLUS 

To many managers, accounting and the preparation of financial 
reports are time consuming chores that have to be struggled 
through. But now, at last, accounting can be simplified. 

GL-PLUS is an accounting system designed for the Apple /// 
computer. It Is a flexible, easy to use, journal-based General Ledger 
system. The computer and GL-PLUS combine to provide you with a 
tool. A tool to make your accounting chores easier. GL-PLUS auto- 
matically guides you through entries and then automatically sorts 
and posts them. 

Report preparation Is a "snap" with GL-PLUS. You select the report 
you wish and the rest is done automatically. GL-PLUS Includes a 
PLUS. The PLUS Is a built-in accounts receivable and accounts 
payable capability that can be implemented anytime you desire. 

Another 'User Friendly' system, flexible reporting and ease of use 
make an excellent accounting package. Developed by Great 
Divide Software, It has a suggested retail price of $495. To be 
reviewed in the June Issue. 

Great Divide Software, Inc., 8060 West Woodard Drive, Lakewood, 
Colorado 80227. (303) 337-0383. /// 
Continued from page 29 

200 FOR loop.2=i0 TO 1 STEP-1 

210 VP0S=loop.2:HP0S=i5 

220 PRINT FN Neg.SQR(vaiue) 

230 vaiue= FN Decreient (value) 

240 NEXT loop.2 

250 VP0S=i2:HP0S=24 

260 PRINT"- They are the sate both ways!" 

270 FOR Coiuin=l TO 80 

272 PRINT"-"; 

274 NEXT Coiuin 

276 VP0S=16:HP0S=9 

280 PRINT"Soie Randoi nuibers" 

290 VP0S=i4 

300 FOR loop. 3=12 TO 77 STEP 12 

310 60SUB 60000 

320 NEXT loop. 3 

330 VP0S=16.-HP0S=48 

350 PRINT"Soie ^orB Randoi nuibers" 

390 VP0S=14 

400 FOR loop.4=i2 TO 77 STEP 12 

410 60SUB 61000 

420 HP0S=40 

430 PRINT teip 

440 NEXT loop.4 

450 VP0S=21 

460 PRINT"Nhat^5 going on?" 

470 PRINT"The second coluin isn't randoi!" 

480 PRINTiEND 

60000 PRINT loDp.3» FN Rnd.l00(-loDp.3) 

60099 RETURN 

61000 teip=loop.4* FN Rnd.l00(-loop.4) 

61099 RETURN 
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by 


Earl Curlson 



TO start off, let me apolosize for the error in last months' column. 
On pase 25, in the third parasraph of the risht hand column, the 
line '30 LETM% = hA%x^' should read '30 LET A% = A% x r. I hope 
it didn't confuse you too much. 

This column is one of a series that is desisned to teach you how to 
use Apple /// Business Basic. Learnins a computer lansuase is 
seldom easy and if you missed the first installment, it will be even 
harder. Therefore, if you don't have it, I sussest you try to get a 
copy. 

I hope you have been practicing, we have a lot to do today! The 
program at the end of last months' article is reproduced here as 
program listing #1. This month we are going to learn all about 
functions, 'FOR.. .NEXT' loops and subroutines: So take an hour or 
so and follow along, you will learn a lot We will start this month 
with loops, so please pull up a chair and continue reading! 



Looping around 



Last month we made a small program that printed out the number 
from through 99 using an 'IF' statement. Vou may not have known 
it, but that was a loop. If you look on pages 11 & 111 of the Basic 
manual you will see the definition of a loop. Very simply, a loop 
describes program statements that are carried out over and over 
again. 

The reserved words 'FOR' and 'NEXT' in Business Basic let your 
programs perform a group of statements a number of times. Pages 
1 1 1 through 1 1 5 show you how to use them. If you look at the first 
program under the 'FOR and Next' title, you will see it is very similar 
to last months' small program that counted from to 99. This one 
counts from to 5. 

As it says, there is another way of constructing those types of 
loops. The next program on that page does just that. Using a 
'FOR.. .NEXT' loop, it also prints out the numbers from 1 to 5. The 
general form of a 'FOR.. .NEXT' loop is - 'FOR variable = start TO 
finish', 'statements to be executed', 'NEXT variable'. 

This statement first assigns the number that 'start' represents to the 
'variable'. It them performs the statements to be executed and 
reaches the 'NEXT'. The 'NEXT' statement increments the 'variable' 
by one (adds one to it) and then sees if it is less than the number 
that 'finish' represents. If the new value of the 'variable' is still less 
than 'finish', the statements are executed again. If not, the loop is 
finished and the program continues with the statements that fol- 
lowed the 'NEXT' (if any). 

What all this means is that the group of program statements 
between the 'FOR' and the 'NEXT' are executed a number of times, 
determined by the values of 'start' and 'finish'. The control variable 
must be either an integer or a real number. It can not be a string or a 
long integer! 

The part on the nesting of a loop inside another loop is good. One 
thing that the manual does not mention is one of the most impor- 
tant things you should talk about when teaching about loops. I 



hope that this next line becomes engraved inside your head 
forever. You must never alter the control variable from within the 
loop. 

What the heck does that mean, right? Consider the following 
program: 

10 FOR variable = 1 TO 10 
20 PRINT variable," "; 
30 variable = variable - 1 
40 NEXT variable 

If you type it in and run it you will get a screenful of the number '1 '. 
Can you see? For this loop to end, the value of the control variable 
must sooner or later reach the number 1 0. But because we alter the 
value of the variable in line #30, it never gets to be 10. 

Inthis small program it iseasyto tell why it'snot working. However, 
if you have a program of many hundreds or thousands of lines, you 
could accidentally change the value of the control variable and this 
program could give you many headaches trying to figure out why 
it's not working. 

It's not that hard to do either. Just a few months ago I spent two 
days trying to figure out why a program wasn't working. I was so 
sure that ever/thing was right! It was driving me crazy until I noticed 
that I had somehow exchanged two statement lines. That's right! I 
committed a very bad programming error, I accidentally altered 
the value of the control variable from within the loop. 

If you read through page 1 15 you will see that a 'FOR.. .NEXT' loop 
can get even more fancy. If you've been following along, you may 
have remembered that even though you can use real numbers for 
the control variable, when the program hits the 'NEXT' statement, it 
only increments the control variable by one. 

Is there are way to change that? Yes! When used in a 'FOR' state- 
ment, the Business Basic clause 'STEP' forces the 'NEXT' statement 
to increment or decrement the control variable by the amount 
specified. Pages 114 through 115 show the different possibilities. 

You can now use a 'FOR.. .NEXT' loop to count by 10's or 20's. 
Backwards, forewards, with fractions - almost anything is possible! 
To show off your new found skill, write a program that counts from 
-2 to -5 by .5 and prints out each value. If you have any problems, 
the answer is just below. 

10 FOR variable = -2 TO -5 STEP -.5 
20 PRINT variable 
30 NEXT variable 

Wow! Would you believe that you just learned all there is to know 
about 'FOR.. NEXT' loops! To become a real expert though, you 
should test yourself by writing small programs that do nothing 
more than count. If you take a little time and practice, things will be 
much easier in the coming months. That's enough for now, take a 
break and when you come back we will learn about another of 
Business Basics' powerful features - subroutines! 
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Subtoutines For All 

Let's say that you dre worki ns on a prosram and you see that two or 
more parts of it dre exactly the same. In other words, throushout 
the program, statements are repeated. If you don't want to type 
them all in in the first place, or if you want to reduce the size of the 
program, you can use a subroutine. 

The Business Basic manuals have a description of subroutines on 
pages 115 through 118, but it is rather cryptic and not easily 
understood. If you read the next few paragraphs you should get a 
good understanding of the 'GOSUB - RETURN' statements. 

Much as the 'FOR.. .NEXT' construct allows you to execute a number 
of statements over and over, the 'GOSUB - RETURN' mechanism 
allows different parts of a program to use the same routines. For 
example, say that throughout your program you need to put a short 
delay loop. If you had to type it in twenty different times, you 
would waste precious memory and time. 

Using a subroutine, you would only have to type it in once! 
Whenever you wanted to use it you would type 'GOSUB xxxxx', 
where xxxxx is the line number of the subroutine. At the end of the 
subroutine you would put 'RETURN'. Below is an example. 



10 
20 
30 
40 
50 
60 



I waste some time.' 



think I'll do it again!" 



PRINT "I think 

GOSUB 1000 

PRINT "Well, that was nice 

GOSUB 1000 

PRINT "All finished, time to end." 

END 

1000 FOR waste = 1 TO 5000 
1010 NEXT waste 
1020 RETURN 

When you run the above program, the computer will print the line 'I 
think I'll waste some time.' and then seem to stop for a few 
seconds. Then it will print the line 'Well, that was nice. I think I'll do 
it again!' and wait a few more seconds before finishing up with the 
line 'All finished, time to end.'. 

What the computer does when it reaches a 'GOSUB' statement is 
this: It GOes to the SUBroutine indicated by the line number 
following the 'GOSUB', and it remembers where it came from. 
When you are finished with the subroutine, the statement 'RETURN' 
tells the computer to go back to wherever it came from. 

You may be wondering by now what line #60 does. As it says, it 
ENDs the program. If it wasn't there, after the program finished 
executing the statement at line #50 it would go down to line 
#1 000 and after a few seconds of looping around, it would hit the 
'RETURN' statement in line #1020. Since the subroutine wasn't 
called with a 'GOSUB' and it doesn't knowwhere to 'RETURN' to, it 
will give an error message. 

Just as 'FOR.. .NEXT' loops can be nested one inside another, 
subroutines can be nested inside other subroutines. Thus, one 
subroutine can call another subroutine and so on. Page 116 tells 
that you can't do this more than 23 times or you will get an error. 

Remember that when a 'GOSUB' occurs, the program remembers 
where it came from. When you have nested subroutines, at times it 
is necessary to tell the computer to forget where it came from. If 



this isn't done, the computer may do something you don't want it 
to do. 

The command to make the computer forget this information is 
'POP'. It has the affect of jumping out of one level of subroutine 
nesting. This command is described on pages 117 and 118. Since 
we aren't going to use it today, I will hold off on a detailed 
discussion for a little while. 

There! We're done with subroutines. For now, that is. We will come 
back to them in a page or so. We're going to talk about functions in 
a moment or two, so you may want to take another short break. No, 
not a week! 

Functionally Speaking 

Since I am going to write part of the column on them, I guess that I 
should tell you what a function is! It is just another way to get the 
computer to give you some type of information. Now, this informa- 
tion will always be in the form of one of the types of information 
that Apple /// Business Basic understands. A function will return 
information in the form of either an Integer, real number, string or a 
long integer. 

Say that you are an engineer or mathematician and you need to find 
out the sine of the number 1.9. If you have a calculator you'll 
probably type in the number and hit the sine key. Looking at what 
you just did, you gave the calculator a number and you told it to 
find that numbers' sine. 

You supplied a value for the machine to evaluate, we will say that it 
is called an argument. The machine performed some operation on 
the value and returned another value. 

This is the exact thing that occurrs in Business Basic. A function 
takes an argument and returns a value. Since It returns a value you 
must tell the computer what to do with it. For example, the 
statement 'SIN (1.9)' in Business Basic causes the computer to find 
the value of the sine of the number 1 .9 . But since a function returns 
a value, where are we going to put it? 

That's right - an assignment statement! You can use the line 'A = SIN 
( 1 .9)' to store the value that the function returns in the real number 
variable 'A'. Once you have captured the number you can print it 
out for the whole world to see with the statement 'PRINT A'. 

What's that you're saying? Can I omit the assignment statement and 
justtype'PRINTSIN (1. 9)'? Why don'tyou try it and see for yourself. 
Test your computers' limits and see what it can and can't do. That's 
the only way you are going to learn, so give it a whirl. 

By now I think you have a pretty good idea about what functions 
dre, so if you'll turn to page 54 in the Business Basic manual you will 
see that they have devoted an entire section to functions. That's 
right - they are very important. 

What I want you to do is to start on page 54 and read through page 
65. This will give you information and examples on all of the 
standard functions that the Apple /// uses. Don't worry, I will be 
right here to help if you have a problem. 

Your first problem is on page 55. The line ')WIDTH=*3.3' is a 
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mistake and should read ')WIDTH=3.3'. See, not even Apple is 
perfect! Pases 57 throush 65 contain all the functions that operate 
on and return strins values. There are quite a few, and v/ith them 
you can perform most any operation that you v\/ould want to do to 
a strins - and more! 

Just as a check, you do remember what strinss are, risht? Good, 
but for my sanity, I'll repeat it. Apple /// Business Basic can 
represent what are called 'Strinss' by enclosins the text that you 
want to manipulate within double quote marks. Thus, the state- 
ment 'A$= "This is a test strins" ' tells the computer to find room in 
memory for the variable with the name 'A' and the type strins- Then 
the computerassisns the words This is a test strins' to that variable. 

Gettins back down to earth, in addition to beins able to convert 
from base 10 to base 16 throush the use of the 'HEX$' and TEN' 
functions, we have the 'INSTR' function. This ver/ powerful routine 
will tell you if a strins is contained in another strins. This is very, ver/ 
useful for prosrammins- Its' description is on pases 63-64. 

While the strins functions are very important, we are so'i^S to 
concentrate on another type of function this month. If you look 
over our sample prosram you will see a number of functions that 
work on just numbers - not strinss. These are appropriately called 
numeric functions and are discussed on pases 65 throush 70. 

The ones we will discuss today are 'SQR', 'INT', 'RND' and the user 
defined functions. By now you may be thinkins that it's an awful lot 
to remember. You're risht, it is. The trick is knowins what to 
remember and what to look up. Yes, you know you can look up 
thinss. Many times I can't remember the exact way to use one of 
the reserved words. When I can't, I just look it up in the manual. 

Gettins back to work, the function 'SQR' is described on pase 68. It 
simply returns the positive square root of the number siven as an 
arsument. So if you type 'PRINT SQR (4)', the computer will 
respond with a '2'. Likewise, 'PRINT SQR (5)' will return 2.23607. 

As with other functions, you may assisn it to a variable. Thus you 
can use the line 'num = SQR (3)' and 'num' will contain 1 .73205. If 
you assisn the value of the square root function to an inteser type 
variable, as in 'num% = SQR (3)', the inteser variable 'num%' will 
contain a 2. As you can see, it rounds the number up to the next 
hishest number. If you try to take the square root of a nesative 
number you will set an error messase. 

The next function we will discuss is 'INT. It is described on pase 66 
of the Business Basic manual. It returns the larsest whole number 
that is less than or equal to the value siven as the arsument. Thus the 
statement 'PRINT INT (8.7)' will return an 8, while 'PRINT INT (7.9)' 
will return a 7. 'PRINT INT (-11.3)' will return a 12. This function is 
very useful! in removins unwanted numbers after the decimal 
point. 

The function 'RND' is also very useful. It is described on pases 66 & 
67. It will return a random positive real number between and 1 . 
For many uses it is very important. Like all of the other functions, you 
must sive it an arsument. 'RND' uses the value of the arsument in a 
special way. If you supply 'RND' with a zero. It will return the last 
random number senerated. An example follows. 

Type in 'PRINT RND (1)' and you will set some random number 



between and 1 . Say it's .302972. If you type 'PRINT RND (0)' you 
will set .302972 asain. Even thoush the 'RND' function returns 
random numbers, usins a zero as an arsument tells it to return the 
last random number it made. This arsument is called a 'seed' and 
what the 'RND' function returns is dependent on what you 'seed' 
the random number senerator with. 

If the 'seed' is positive, the function will return a new random 
number each time it is used. If the 'seed' is nesative, it will return a 
random number sequence that will follow the same pattern each 
time the function is called with a positive arsument. Thus, you can 
force Business Basic to return numbers that are random, but can be 
repeated if you use the same nesative number as the initial 'seed'. 

A different sequence is initiated by each new nesative arsument. 
The primary reason for this is to initialize a repeatable sequence of 
random numbers. This is invaluable when debusS'^S a prosram 
that uses 'RND'. 

Now that we have a few of the basic functions down pat, we are 
set to tackle the hard one - User Defined Functions! These are 
functions that the user can create out of any of the built-in func- 
tions. This is described on pases 70 throush 72. 

While hard to describe, they are very easy to make and use. Lets so 
ahead and make one for practice. How about a function that takes 
the square root of a number and then adds 1 to it? Why not, risht? 
What we need is somethins that performs the followins function: 
'sqr.plusi (x) = SQR (x) + 1'. Type in the followins prosram: 

10 DEF FN sqr.plusi (x) = SQR (x) + 1 
20 PRINT FN sqr.plusi (4) 
30 PRINT FN sqr.plusi (100) 

If you run the above prosram, you will set a 3 and an 1 1 as answers. 
The prosram first DEFines a new FuNction with the name 'sqr.plusi ' 
in line #10. Then the function is called first in line #20 with the 
arsument 4. The function then takes over and proceeds to take the 
square root of the number 4. This result is added with 1 and the 
result is returned and printed. In line #30, the function is called 
with the arsument 1 00. Just as before, the function takes the square 
root of the arsument and adds 1 to it. This result is then returned 
and printed out. 

An important thins to learn is that while line #10 defines the new 
function 'sqr.plusi ' with the variable 'x', that variable does not have 
to be used to communicate with the function. Just as a resular 
function will work with any value passed to it (not just the number 
in the variable 'x'), user defined functions allow you to sive any 
variable as an arsument. 

Say you're an ensineer or mathematician and you need to use the 
hyperbolic functions. At first slance, the built-in functions of Busi- 
ness Basic don't seem to have what you're lookins for. However, if 
you remember that you can build new functions out of the built-in 
ones, and jos your memor/ (and some books), you can come up 
with the necessar/ formulas. 

The hyperbolic sine can be computed with the followins function, 
'sinh (x) = (EXP (x) - EXP (-x)) / 2'. If you define a function with the 
line '10 DEF FN sinh (x) = (EXP (x) - EXP (-x)) / 2', you can use the 
new function with an assisnment statement like '20 value = FN sinh 
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(1 .41421 )'. After you run the prosram, the value of the variable 
Value' should be 1.93507. 

If you look over the examples on pases 70 throush 72, you will see 
that the uses of these user defined functions are almost endless. 
Practice with these definitions and by all means make up your own! 
Like I said last month, if you want to learn how to program in 
Business Basic, you will have to do all the examples I give and 
more. 

Guess what folks? That's right - after all we learned so far, we are 
ready to look at program listing #1 and understand it! Starting at the 
top we see that the first four lines are user defined function 
definitions. 

Line #10 contains a function that takes the value of the argument, 
adds 1 to it and returns the result. Line #20 has a function that does 
the opposite: it returns the value of the argument minus 1 . These are 
appropriately called Increment & Decrement. 

Line #30 is also very simple. It defines the function with the name 
'Neg.SQR'. What it does is take the square root of the argument and 
multiply it by -1 . That is all that this function does. I've gotten some 
mail about negative square roots and their applications, so let me 
put this to rest. I only intended for the function to take a square root 
and multiply it by-1 , as instructional into what you can do with user 
defined functions - nothing more. 

Anyway, line #40 is a function definition whose function will return 
a random number from to 99. It uses the argument 'seed' to be 
the argument for the 'RND' function. This can and does produce 
some surprising results when used in the program. When the 'RND' 
function returns a value. It is multiplied by 100 to produce a 
random real number. I wrote this function to return only whole 
numbers and that is the reason for the 'INT' statement. 

Line #50 clears and moves the cursor up to the left hand corner of 
the screen. Then the statements in line #60 move the cursor down 
to the 28th column of the 6th row. Line #70 then prints out some 
words and we get to line #80. Here the cursor is moved down to 
the 12th row and line #90 prints out some more words. 

Lines #100-140 are the programs first loop. As you can see the 
control variable (the one that is incremented) is 'loop.1 '. This loop 
goes from 1 all the way up to 10. Line #110 takes the value of the 
variable Value', which is initially zero, and uses the 'Increment' 
function to add one to it. The next line moves the cursor to the first 
column of the line specified by the variable 'loop.1 '. 

If you remember, this loop goes from 1 to 10, so what line #120 
does is move the cursor from row 1 to 1 on the screen. We do it so 
that we can print out the numbers at certain places on the screen. 
Line #1 30 uses the function 'Neg.SQR' to take the square root of the 
value of the variable 'value', which will also go from 1 to 10, and 
multiplies it by-1 . After the function is finished, it prints the result in 
the specified column and row. 

Lines #200-240 are almost a mirror (reverse) image of the last five 
lines. This loop goes from 10 down to 1 (note the STEP value of -1 ). 
Line #210 positions the cursor on the line specified bythe variable 
'loop.2', but just as important, it positions the cursor at the 15th 
column of that line. This causes the numbers to be printed starting 



on the bottom row (#10) and working up to the first row side by 
side with the first numbers that were printed. 

Lines #250-260 print out some more text, while lines #270-274 use 
a 'FOR.. .NEXT' loop to print out a line of dashes '-' that cuts the 
screen in half. Lines #276-280 prints out some more words, while 
line #290 positions the cursor for the next printing. 

The exciting stuff starts at line #300. Here we see there is a fairly 
simple loop whose control variable is 'loop.3'. It starts at 12 and 
goes up to 77 - but the 'STEP' size is 1 2. That is to say, as the loop is 
executed, 'loop.3' takes on the values 12, 24, 36, 48, 60, 72, Line 
#310 does a 'GOSUB' down to line #60000. 

Here we perform one statement and then 'RETURN'. That one 
statement is fairly complicated though. What it does is print out a 
number. This number is computed from a multiplication of the 
result of the function 'RND.1 00' and the value of 'loop.3'. When it 
calls the function, it passes as the argument, the negative value of 
the variable 'loop.3'. 

If you remember what the 'RND' function does, when we give it a 
negative value, it returns the same values over and over when given 
the same argument. When the loop that starts at line #300 finishes, 
the loop at line #400 begins. 

This loop starts at 12 and goes up to 77, just like the last loop. Line 
#410 causes the subroutine at line #61000 to be executed. If you 
look at the difference between line #60000 & 61000, you will see 
that the only change is in the variable names. 

When you run this program, the last two columns that are printed 
are the same. Since these numbers are random, you would expect 
that they would be different- but they aren't. If you remember our 
discussion about the 'RND' function, you will see why these two 
columns are the same. 

That's right! Because they both use the same numbers as argu- 
ments, they form a repeating sequence. See, once you know what 
the words mean, it gets a whole lot easier. 

If you don't see how and 'why' everything works, study the pro- 
gram a little more. You have to practice or you will never learn 
Business Basic. That's all for this time. Next issue we will take a 
closer look at strings and learn about Apple Business Basic I/O 
(input/output). If you want to work ahead, read the parts of the 
manual concerning strings. That should be enough to satisfy you 
until next time! Coming up soon we're going to make a 'Hello' 
program that will perform many useful functions. Until them, 
remember - if you get discouraged, don't give up - tr/ harder! /// 

10 DEF FN Incr8ient(nui)=nui+i 

20 DEF FN DecreiBerjt(nufli)=nut-i 

30 DEF FN NeQ.SQR(nu«)=3QR(nuii)l-l 

40 DEF FN Rnd.iOO(5eed)=INI(RND(5e8d)llOO) 

50 TEHiHOHE 

60 VP0S=e:HP0S=28 

70 PRINT^Neoative squa^rG roots frosi 1 to 10" 

80 VP0S=12 " 

90 PRINT"6oinQ down.... Going up'' 

100 FOR loop. 1=1 TO 10 

110 vaiui= FN Increnent (value) 

120 VPQS=loop.l:HPOS=l 

130 PRINT FN Neq.SeR(value) 

140 NEH loop.r 
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ON Pascal 










by Louis Hanson 



Hello there! This column is for those of you who want to learn the 
remarkable Pascal computer lansuase. I will teach, guide and 
prod you until you have a good working knowledge of what Pascal 
is - and what it can do for you. Along the way we will learn how to 
use all the elements of the Apple /// Pascal system, including the 
Editor, which doubles as a fine word processor. 

As a start, we should first think of why we need to use Pascal. 
Perhaps you ascribe to the belief that Basic causes brain damage, 
and would like to keep your sanity. Maybe it's because many of the 
programs contained in this magazine are written in Pascal, and you 
want to know what you are typing in. Or quite possibly it's that you 
just want to learn new things and you hear that Pascal is THE' 
computer language to use. 

For whatever the reason, I am glad that you are still reading, it must 
mean that you have some interest. Why Pascal? Good question! I 
hope I can give a good answer. Before we get down to business, 
let me say that this column is not just for people v/ho already know 
how to program. Indeed, it may be easier for those of you who 
don't have other computer language quirks to unlearn. 

The computer language Pascal was defined by computer scientist 
Niklaus Wirth. His initial objective was to make a language that 
could be used to teach students good programming skills. As its 
popularity spread, other people began to see that Pascal was a 
very good language. 

At the University of California at San Diego, a very important version 
of Pascal was developed. Called UCSD Pascal, It is the basis of 
Apple /// Pascal. It uses what is called 'P-Code', which will be 
described in a few lines. One of the wonders of Pascal is that it can 
be transported from one computer to another very easily. Since 
UCSD Pascal is available onjust about everycomputer made, most 
any program you write on your computer can be used on another 
computer that has UCSD Pascal. 

This opens tremendous possiblitles for software marketing. Write 
one applications package and you can use it on scores of comput- 
er systems. As some advertisements say, the same pacakge can run 
on an Apple to a Zenith. While there are some limitations, this does 
describe the abilities of UCSD Pascal. 

Sounds pretty good, right? Well, before you do run out and spend 
about $200 on the Apple /// Pascal package, let me tell you some 
more of its good and bad points. Yes - It does have some bad 
points! The minimum configuration is a 128K Apple /// with at 
least one external disk drive. Two external drives are recom- 
mended, while a Profile hard disk is best. 

The Apple /// Pascal system consists of three diskettes that con- 
tain all the files needed to implement UCSD Pascal on the ///, and 
four instruction manuals that tell you just about everything you 
need to know about the package. One of the nicest features is the 
Editor. Used to create and modify the program statements you 
type in, it can be used to write letters and do other word process- 
ing tasks. 



If you have used Basic, you know that you can type 'PRINT 821 + 
180', press the 'RETURN' key and the result '1001' will be imme- 
diately printed on the screen. To get the same result in Pascal takes 
a bit more of work. Vou need to know how to use the Editor and 
Compiler to get it to work. The Pascal program to add 821 and 1 80 
is below. 

PROGRAM Additi on Te st: 
BEGIN 

WRITELN(821 +180) 
END. 

To make it work, you have to use the ed i tor to create the I i nes of text 
above. Then you have to save the file on disk and exit the editor. 
Next you must compile the program to a form the computer can 
execute. Finally, you Run the program to get the answer (1001 ). 

Seems like a lot of work, doesn't It? If you make an error in typing In 
a Basic statement, it is usually Immediately detected and you 
simply retype the line. With Pascal, the error is not found until you 
compile the program (or later). If you want to fix it, you must go 
back to the editor and fix the mistake. After fixing it, you then have 
to re-compile it. 

As you can see, Basic is better for short programs. As programs get 
longer, in Basic they get harder to read and understand. One of 
Pascal's big points is its readability. Because Pascal allows (and 
encourages) many comments, it is much more legible as the size 
gets bigger than a comparable Basic program. 

By now you must be asking yourselves, "What is this Compiling bit 
about?" The answer is a little complicated and will take a few 
paragraphs. The Basic language is called an interpreter because 
when a program is "RUN", the system scans each line of your 
program for words it understands. As It finds these words, built in 
instructions are called that performs the action that those words 
mean. For example, when the Basic interpreter sees the line PRINT 
"Hello", control is passed to a section of the interpreter that 
handles 'PRINT' statements. Here, the print instruction is turned into 
a set of machine language Instructions that the computer can 
execute directly. 

This scanning and interpreting takes up a lot of time. Consequently, 
the time that a Basic program takes is much slowerthan whata pure 
machine code version of the same program would take. With 
Pascal you must first type in the program and then Compile it. The 
Compiler converts your Pascal statements into a set of instructions 
that the computer can use directly. These instructions are called 
the 'object code', while the original statements are called the 
'source code'. When you Run a Pascal program, it is this 'object 
code' that is executed. Thus a Pascal program will be able to go 
faster than its Basic counterpart because there is little scanning and 
interpreting, just execution! 

If you noticed I said that the Compiler produces 'object code' and 
not machine language. This is due to the fact that we are working on 
a P-Code version of the language. For all of you who have been 
waiting for me to explain what P-Code means, here goes! 
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When UCSD pascal was in its infancy, it was determined that it 
would take years to write a Compiler for each different computer 
that produced machine lansuase that each individual computer 
could execute. It was decided that the UCSD Compiler would put 
out 'P-Code' instead of machine code. Compilers would put out 
the same P-Code resardless of the computer used. Thus, only one 
Seneral Compiler was made for all computers. 

This 'P-Code' is a set of instructions that needs to be interpreted 
(like Business Basic) to work. The P-Code interpreter (SOS.INTERP 
on the Pascal system disks) analyzes each P-Code instruction and 
performs the matchins action for that instruction. Since the P-Code 
has already been scanned for errors durins compilation, the Pascal 
interpreter can work much faster than the Basic interpreter. 

Each computer can use the same seneral Pascal Compiler, but 
each must have its own interpreter. Bis deal, huh? We traded 
writins a Compiler for just our machine into writins an interpreter 
for just our machine. Well, it seems that the interpreter is very 
simple to write for any machine. Because each computer system 
compiles into the same P-Code, compatibility is not a problem. 
With minor restrictions, you can execute the P-Code of one com- 
puter on another. 

Since UCSD Pascal was so easy to adapt to all systems, its popular- 
ity has spread unti I today most every micro and mini computer has 
it. Now it's about time to set started. This month we will learn how 
to use the Editor and Filer. We will also write our first Pascal 
prosram. So kick off your boots, roll up your sleeves and let's s^t 
crackins! 

The Filer 

Once you set the Pascal packase for the Apple ///, the first thins 
you should look at is the 'Introduction, Filer, and Editor' manual. It 
holds most of the information needed to start usins Apple /// 
Pascal. If you turn to the Preface you will see that this is the book to 
start with. Readins the overview in chapter 1 , you should follow the 
instructions and make copies of your Pascal system diskettes. 

Also in chapter 1 you will find information on rearransins the files 
on the diskettes. This is very important! If you have a Profile hard 
disk drive, follow the instructions in the Profile manual to put the 
Pascal files on the hard disk. This will result in a tremendous speed 
increase when operatins the Pascal system. If you only have one 
external disk drive (excludins hish density drives), you will find 
workins conditions impossible. The only remedy is to buy another 
disk drive. C'mon, the prices aren't that hish! 

If you don't have a hard disk drive, to use this article series as a 
tutorial, you must transfer the file 'SYSTEM.FILER' from PASCAL1 to 
the disk in your second external drive and then delete 'SYSTEM- 
.FILER' from PASCAL1 . Since you can't delete the file by usins the 
Filer (it's sort of like committins suicide), use the System Utilities 
Disk to transfer and delete the file. The reason for this is we are 
Soins to need some space on PASCAL1 to put prosrams, and with 
the Filer there, there just isn't enoush room. 

Since this isyour introduction toApple/// Pascal, we should start 
at the besinins- As with all lansuases on the///, you have to boot 
the appropriate disk to use the lansuase. Insert the copy of PAS- 
CAL1 into the built-in drive and either turn on the computer or 



press 'CONTROL RESET'. In about thirty seconds a screen like the 
one on pase 4 will appear. 

On pases 4 and 5 you will also find information on the 'Prompt 
lines'. The mail level command prompt line is the sinsle most 
important place in Apple/// Pascal. From here you can invoke and 
enter the Editor to make your Pascal prosrams, the Filer to perform 
file operations, the Compiler to translate the prosram you wrote 
with the Editor to a form the computer can execute, the Assembler 
to make assembly lansuase routines that your Pascal prosrams can 
use, and the Linker to link tosether your Pascal and Assembly 
lansuase routines. 

Chapter 2, "The Command level", describes all of the options 
available from the command prompt line. It may not be the best of 
readins but it does have some important information. We aren't 
soins to learn all of those commands today, but you may want to 
look it over for the future. 

RiSht now we are soins to start usins the Pascal system, so you 
should have booted the system as described a couple of para- 
Sraphs aso. When the command prompt line appears, press the 'F' 
key once and see what happens. The disk drive will make some 
noise and in a few moments the Filer prompt line will appear. 
Chapter 3 describes the operation of the filer, so open the manual 
to pase 30 and follow alons- 

As the chapter says, the Filer manipulates files. The first few pases 
Sive a brief overview of the options of the filer and their use. The 
rest of the chapter describes in depth the options and how to use 
them. Inthe next few parasraphs we will discuss these options and 
what they are for. 

In many ways the Filer is a 'mini' System Utilities Prosram. Indeed, it 
does most of the thinss that the System Utility Prosram does, and a 
few that it doesn't! Just as the System Utilities Filer can list the files 
on a directory, the Pascal Filer can do the same thins- At the Filer 
command level, press the 'L' key once. Pases 47 to 52 tell how to 
use this command. Generally, just type in the pathname of the 
directory that you want to list. After typins 1', enter somethins like 
'.D1' or '.D2' and the specified directory will be listed to the 
screen. Vou can also send the listins to a printer or disk file by 
enterins a destination file specification as described on pase 51 . If 
you want to send a listins of the files of the disk in the internal drive 
to the printer, you would enter (after typins 1') '.D1, .PRINTER'. 

If you have a hard disk storase system, you probably use subdirec- 
tories. When listins the contents of a directory with the list com- 
mand, at times it is helpful to see the contents of all the subdirecto- 
ries. The 'E' command of the Filer does this. It is described on 
pases 51 and 52 of the manual. At the Filer command level, type 
the 'E' key and enter the directory name. Just like the 'L' command, 
you can send the listins anywhere. 

If a device driver with the name '.PRINTER' is not confisured into 
your system, you will set an error messase when try ins ^o print to it, 
as in the above commands. How can you find out what devices are 
confisured into your system? Vou could use the System Confisura- 
tion prosram to do it, but the Pascal Filer has a command that 
allows you to see all volume names, device names and the device 
numbers of all the input and output devices whose drivers have 
been confisured into the system. To use this command, from the 
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Filer command level type V for Volumes. This is described on 
pases 46 to 47. 

The Filer also allows you to transfer files from one place to another. 
These transfers can be quite complex and they are described on 
pases 52 throush 61 . You can copy file to file, volume to volume, 
subdirectory to subdirectory and more! Since we won't be doins 
much transferins yet, I'm not soins to spend much time discussins 
this command. If you want to learn everythins there is to know, 
read the above mentioned pases and follow the examples. 

You can also use the Filer to create new subdirectories and reserve 
space on a disk for a file. This command can be used by typins 'M' 
for make. Pase 62 and 63 tell all the options of this command. 
When you're finished readins those pases, sive yourself a test. Try 
to use the Make command of the Filer to create a subdirectory 
named TEST.DIR'. After typins 'M' you should enter '.D2/TEST.DIR!'. 
This will create a one block Ions subdirectory named 'TEST.DIR' on 
the disk in drive #2. 

The Chanse command allows you to rename any or all of your files. 
It is described on pases 63 to 68. After readins over that informa- 
tion, use the command to rename the subdirectory you just made 
with the name 'NEW.SUBDIR'. The command sequence is 'C - to 
invoke the Chanse command, '.D2/TEST.DIR, .D2/NEW.SUBDIR' 

The Filer option 'R' for Remove, lets you delete files from your 
diskettes. After readins over the decription on pases 68 to 70, use 
the command to delete the subdirectory we have been workins 
with. By nowyou should be able to fisure it out without my sayins 
how, so I won't! 

Since we aren't soins to use Apple ][ formatted disks, I am not 
soins to discuss the Krunch or eXamine commands. One of the 
ones we are soins to discuss is the Zero command. It will delete all 
the files on a directory or subdirectory. The description is on pases 
71 and 72. Since this command deletes one file at a time, it takes a 
while. Therefore, you should limit its use to erasins the files on a 
subdirectory. This is because it is much faster tojust format the disk 
if you want to erase all the contents. 

The Prefix command of the Filer is very useful. It is described on 
pases 73 throush 75. As the manual states, it is a bis timesaver. You 
can set the Prefix to whatever subdirectory you are workins on and 
then only refer to the local pathname. My hard disk has a subdirec- 
tory named 'PASCAL' and on that subdirectory is another subdirec- 
tory with the name 'WORK. AREA'. This is where I store all the Pascal 
files that I am currently workins on. When I boot up Pascal, I use the 
Filer to set the Prefix to '.PROFILE/PASCAL/WORK.AREA'. After 
doins this, I can simply use the local name (the name of the files in 
the subdirectory 'WORK.AREA') when Editins, Compilins etc. the 
files I am workins on. 

The Filer also allows you to read and chanse the system clock with 
the Date command. Even if you don't have a workins clock 
installed inyoursystem, the Pascal Filer will rememberthe date that 
it was last used, and use that when savins or updatins file informa- 
tion. To read or chanse the date, look over pases 75 and 76 and 
then press 'D' at the Filer command level. Now enter the current 
date and press return. You should see the disk in the internal drive 
come on for a second or two while the date information is stored 
on disk. Yes, that's how the computer remembers the last time it 



was used. This date information is stored in the file 'SYSTEM.MIS- 
CINFO' on the boot disk. 

The Alter command of the Filer can be used to chanse a files type, 
write-protect status and date of last modification. It is described 
on pases 76 and 77. To use it, type 'A' at the Filer command level 
and then follow the instructions as listed on the above mentioned 
pases. For now you will probably only need this command to 
write protect your files so that you can't accidentally delete them. 

One handy utility option is the Bad Blocks command. It will find 
any blocks on your diskettes that are damased and not useable. 
Described on pases 84 to86, it isverysimllarto the Verify option of 
the System Utility prosram. You should use It everytime you format 
a disk, to check for flaws. 

Once you're finished usins the Filer, you can use the Quit option to 
return to the main command level. To use it, just type 'Q' and the 
main command level prompt line will come up asain. In a few 
parasraphs we will learn about the workfile and its related com- 
mands, but for now we're done talkins about the Filer. 

That's it! You now know how to usejust about all of the commands 
of the Filer. You're risht, it is a lot of information. But if you want to 
learn Pascal, you're soins to have to read and read and read. And 
when you finish readins, you have to test your knowledse by 
practicins- If I could hold your attention this far, you must have 
enoush interest to practice. Before we continue, first take a break. 
You deserve it! When we start asain, we are soins to jump on over 
to the Editor and learn how to use it to write Pascal prosrams! 

The Editor 

Before tryins to use the Editor, make sure you have a copy of 
PASCAL2 in the second disk drive. At the main command level 
press the 'E' key once. This invokes the file 'SYSTEM.EDITOR' from 
the disk. Chapter 4 (pases 92 throush 1 54) describe the functions 
of the Editor. This chapter contains very helpful information for 
learnins how to start usins the Editor. 

If you read throush the first three pases you will come to a pase 
titled 'Startins a New File'. If you have been followins alons, your 
screen should look like the one under the first parasraph of pase 
95. Since we are startins a new file, when you set this prompt, just 
press 'RETURN'. Consratulations, you're now 'in' the Editor. 

Just as the Filer and the main command level have their own 
prompt lines, the Editor has one. It is shown on pase 94. As with 
the other prompt lines, to use one of the options, simply press the 
appropriate key. This month we are soins to learn the 'I, D, R, A, J 
and Q' options. These are the Insert, Delete, Replace and Adjust 
keys, and the Jump and Quit commands. 

Press the 'I' key once to set into the insert mode. If you look at the 
prompt line you will see that it has chansed as shown on pase 95. 
These are the options available at this level. You can type in text, 
use the left arrow key to remove the character to the left of the 
cursor, press 'CONTROLX' to delete an entire line, 'CONTROL C to 
accept the text you just typed in, and 'ESCAPE' to return to the main 
prompt line of the Editor without acceptins the textyou just typed. 

The best way to learn is to try, so at the Editor command level press 
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T to insert some text. Now enter the lines below, rememberins that 
at the end of a line press 'RETURN'. Don't forset the semicolon at 
the end of the first line! 

PROGRAM Additionj;est; 
BEGIN 

WRITELN(821 +180) 
END. 

After you type in the line 'WRITELN (821 +180)' and press 'RETURN' 
you will have a problem. The cursor will drop down and be flush 
with the W in 'WRITELN' instead of beins flush with the left side of 
the pase. To make the cursor be flush with the left edse of the 
screen, type 'CONTROL C to set to the Editor command level and 
then 'A'. This is the Adjust command. As the new prompt line says, 
you can press 'L' to move the cursor to the left of the screen, 'R' to 
move it to the risht, 'C to center the I i ne the cursor is on, or use the 
arrow keys to move the line. For our example, press 'L' to move the 
cursor over to the left of the viewport and then press 'CONTROL C 
to exit the Adjust mode. 

When you finish the last line ('END.') press 'CONTROL C to have the 
com puter accept the text you j ust typed i n. As soon as you do that, 
you will asain see that Edit prompt line. This means that the 
computer has stored the lines you just typed in. Since we would 
like to see the computer execute the prosram we must compile it. 
Type 'Q' for quit and you will be sreeted with a screen like the one 
on pase 102. These are the options of the Quit command. 

Since our prosram is small and doesn't take up much space, we 
can use the workfile to store our prosrams. Type 'U' for Update. 
Once you do this, the disk drive will make a little noise and then 
stop. You just saved the lines you just typed in to the disk file with 
the name 'SYSTEM.WRK.TEXT on your boot disk. This is a very 
special file, which we will discuss further in a moment. 

Now that the file is stored on disk, you can exit the Editor with a 
press of the 'E' key. Asain, the disk should make a little noise and 
the main command level prompt will appear. Since we have to 
translate the lines we just wrote to a form that the computer can 
execute, we must Compile the prosram. To do this, simply press 
the 'C key. 

The computer will search for the file 'SYSTEM.COMPILER' on all of 
the disks in the system. If it doesn't find the file, you can't compile 
your prosram and you will s^t an error messase. If all soes well, 
some stranse lines will appear tellins you that the Compiler is 
runnins and it is translatins the lines of text you wrote into a form 
that the computer can execute. If all soes well, in a few moments 
the main prompt line will appear asain. This tellsyou that you made 
no typins errors that the Compiler could detect and the prosram is 
read to Run. 

You may be wonderins how the Compiler knew what prosram to 
compile, so here's the answer. If you remember, when we saved 
the file we had the computer store it in the file '.D1 /SYSTEM.WRK- 
.TEXT'. As I said, it is a very important file. When you try to compile a 
prosram, the Compiler looks on the disk in the boot (internal) drive 
for a file with the name 'SYSTEM.WRK.TEXT'. If found, it compiles 
that file. If you are not usins the workfile, it will ask you what file to 
compile. We will later learn how to save the file somewhere other 
than the workfile, but for now it makes thinss a little easier and 



quicker so we will use the workfile. 

If you didn't have any errors in your prosram, and it compiled 
without a hitch, you can press the 'R' key to Run your prosram. 
Under the prompt line will be the line 'Runnins-..', and under that 
the prosram will write the value of 821 + 120 (1001 ). Consratula- 
tions, you just wrote, compiled and executed your first Pascal 
prosram! 

Press the 'F' key to enter the Filer and then press the 'L' key to list the 
files on a disk. When the prompt appears, enter '.D1' and then 
press 'RETURN'. This command will listall the files on the diskette in 
drive #1 . In that listins you will see the files 'SYSTEM.WRK.TEXT' and 
'SYSTEM.WRK.CODE'. The first you should recosnize as the file with 
the lines you wrote and then compiled. What is the second one, 
thoush? 

If you look back, you will remember that we compiled the file 
'SYSTEM.WKR.TEXT'. Since the computer can not execute that file, 
the Compiler made another file - the 'object code' of the first file. 
This is the file that was Run. The word 'code' is the key! The file with 
the prosram lines that you typed in has the suffix 'JEXl'. This is the 
text file. The file that the Compiler created had a suffix of '.CODE'. 
This is the code file that was created by the Compiler and later 
executed with the Run command. 

Say that you no lonser want to add 821 and 180, but you want to 
multiply 27 by 8. We obviously need to chanse the prosram, so 
type 'Q' to exit the Filer, and the press 'E' to enter the Editor. If you 
remember the last time we used the Editor, it asked us for the file to 
use. Now, since there is a workfile, the Editor automatically reads in 
the text from the file 'SYSTEM. WRK.TE>Cr'. After a few seconds you 
should see the Editor prompt line and be ready to chanse the 
prosram. 

While in the Editor, you can use the four cursor control keys to 
move anywhere within the file that you are currently workins on. 
Use those keys to position the cursor over the plus '+' sisn. Now 
press the 'D' key once. If you look at the prompt line, it now says 
'>Delete' and some more words that indicate what you can do 
with this option. Press the space key once and the plus sisn will 
disappear. To make the chanse permanent, press 'CONTROL C. 
Since we want to multiply and not add, press the T key to insert 
more text and then type '*' and press 'CONTROL C. 

Wejustchansed the addition to a multiplication, but we need to 
fix the numbers. We can now learn the Jump command to speed 
the chanse. The cursor should be somewhere in the middle of the 
lines on the screen. To move it to the besinnins of the file, press the 
'J' key. A new prompt line will appear. Press the 'B' key and the 
cursor will immediately jump to the besinnins of the file. You can 
also jump to the end of a file by pressins 'J' and then 'E' for end. It 
doesn't matter if you type the letters in lowercase or uppercase 
letters, the computer understands what you mean. 

Since we chansed the prosram from addition to multiplication, 
we may as well chanse the name of the prosram. Use the 'J' key to 
move the cursor to the besinnins of the file and press the space 
bara few times to position the cursor over the 'A' in 'Addition'. Hit 
the 'D' key to enter the delete mode and then press the space bar 
eisht times. Now press 'CONTROL C to make the chanses perman- 
ent. Finally, press the 'I' key to insert new text and then enter 
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'Multiplication' and 'CONTROL C to finish up the insertion. 

Before we sot sidetracked with the Jump command, we were 
Soinstochansethe number 821 to 27 and the number 180 to 7. 
We can use the Replace option of the Editor to accomplish this. 
With the cursor at the besinnins of the file, press 'R' and then enter 
'/821//27/'. The Editor will then find the characters '821' and 
replace them with '27'. Likewise you can chanse the number 1 80 to 
7. This command is described in a little more detail on pases 130 
to 135. 

We could have used the Delete and Insert commands to perform 
this chanse, but it is very important to know many different 
methods of doins thinss. There are a number of other helpful 
commands that we will set to know, but for now the few that we 
have mentioned will be more than enoush to s^t us throush our 
besinnins prosrammins attempts. As I said, the Editor can double 
as a fine word processor and if you have ever used a word 
processor you should see what I mean. 

Since we have chansed our prosram, we can now save it back on 
the disk and leave the Editor. Press 'Q' to exit the Editor, and then 
'U' to Update the work file. After some disk activity, press 'E' to exit 
the Editor. Now press the 'R' key to run the prosram and... Hey wait 
a minute, we still s^t 1001 as an answer! What went wrons? Oops, 
we forsot to compile the prosram! Because we didn't compile the 
updated prosram, the computer executed the old 'SYSTEM.WRK- 
.CODE' when we hit 'R'. 

To compile the updated prosram, press the 'C key to besin. Since 
we are still usins the workfile, the Compiler didn't ask us for a file to 
compile - it just used the workfile. After a few seconds the main 
level command prompt line will come up asain and the compila- 
tion will be done. Now press the 'R' key and you will be sr^^ted 
with 216, which is the result of the multiplication 27 * 8. 

One of the most important thinss in learnins somethins new is not 
beins afraid to make mistakes. The more mistakes you make at the 
start, the quicker you will be able to correct them down the road a 
few months. Therefore, lets put an error in our prosram and learn 
how to fix it. 

At the main command level, type 'E' to enter the Editor. Since we 
are soins to make an error on purpose, let's chanse the first word 
'PROGRAM' to 'PROGRAN'. Position the cursor over the 'M' in 
'PROGRAM' and hit the 'D' key once. Now press the space bar once 
to delete the letter, and then 'CONTROL C. Next Insert the letter 'N' 
where the 'M' was. To finish, press 'Q' and then 'U' to quit and 
Update the file. 

At the main command level hit 'C to compile this new prosram. 
Ouch! What happened? The Compiler stopped with a weird 
messase. Somethins about an error in one of the lines. To see 
exactly what error and where it occured, press 'E' to so to the 
Editor. After a few moments the computer will display the error 
messase 'Error in declaration part. Type <space>'. Once you 
press the space bar, this handy little feature returns the cursor over 
the offendins part of the prosram. In our case it is at the end of 
'PROGRAN'. 

When you think about it, this Pascal system is very nice because it 
cantellyou notjust where your errors are, but what type of error it 



was! This is very useful in debuss'^s Ions and complex prosrams. 

If you have been followins alons, you know that you have had to 
wade throush a few pases of thinss that aren't terribly excitins- 
After all, you did start readins this column with the impression that 
you were soins to learn Pascal, risht? Well, the Pascal system 
comprises three disks of prosrams and hundreds of pases of 
readins. I think the keyword here is 'system'. Pascal isn't just a 
lansuase, it's an idea - a feelins - a lot to learn! 

Before we can really start in on the lansuase, we must do the 
backround work. We have to learn about the Filer, the Editor, the 
Compi ler and other features of the system, or we wi 1 1 never be able 
to fisure out what Pascal is all about. Therefore, I think that if you 
want to learn Pascal you have to be very, very patient. You'll learn 
Pascal, but it isn't soins to happen overnisht. 

At this point in time, if you have been followins my lead, you 
should have a sood idea about what the Pascal system is all about. 
You have used the Filer to create, modify and delete files. You used 
the Editor to make the source text for your Pascal prosrams, and 
you used the Compiler to compile that source text into a form the 
computer can understand. You have done all of the basic opera- 
tions necessary to use the Pascal system, so what are we waitins 
for? Let's learn Pascal! 

First Steps 

If you've been followins alons, up to this point we have been 
readins out of the 'Introduction, Filer, and Editor' manual. Now we 
are soins to take that bis step and look into the 'Prosrammer's 
Manual Volume 1 '. If you open up that book and look at pases 2 
throush 6, you will see a fairly sood introduction to the Pascal 
lansuase. 

As it says on pase 3, Pascal prosrams doesn't have line numbers. 
This free-form method of prosram desisn allows a much more 
readable prosram than in Basic or Fortran. This and other features of 
Pascal make prosrams much easier to write and maintain than 
equivalent prosrams written in other lansuases. 

Pase 5 shows the s^neral structure of a Pascal prosram. Just as is 
shown, all Pascal prosrams have a number of parts. To start a Pascal 
prosram, the word 'PROGRAM' must come at the besinnins of the 
file, followed by the name you want to prosram to be called and a 
semicolon. Note that this is not the same as the name of the file 
stored on the disk. 

Some of the optional items that also can be included are the 
declarations of all variables and data types. If you don't know what 
these words mean, don't worry - I'll tell you in a little while. Next 
comes function and procedure definitions. The last part of a Pascal 
prosram is the word 'BEGIN' followed by any number of state- 
ments that are separated by semicolons, and the word 'END', 
followed by a period. 

If you look back at the two prosrams which we already made, after 
the word 'PROGRAM' we put the names 'Addition-Test' and 
'Multiplication-Test'. This is the prosram headins- Next in our 
prosrams came the word 'BEGIN'. This tells the compiler that the 
lines followins this word are the main part of the Pascal prosram. In 
the PROGRAM 'Addition-Test', the next lines read 'WRITELN (821 + 
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180);'. This is a Pascal statement that prints out to the screen the 
result of whatever is inside its parenthesis. In our example, the 
computer added the numbers 821 and 180 and then printed out 
the sum to the screen. The exact meaning of 'WRITELN' is it instructs 
the computer to Write a LiNe to the screen. 

Enter the Filer by pressing the T' key and then hit the 'N' key. After a 
second or two, when the new prompt line comes up, press T. If 
you remember, we have been working with the 'Workfile'. When- 
ever we enter the Editor it checks for a workfile. If it finds one, it 
loads it from the disk whether we wanted to use it or not. Since we 
now want to write another program we can use the 'N' command 
of the Filer to remove the workfile from the disk. You should not use 
the Remove command to do this because the New command 
updates some pointers in memory to say that there isn't a workfile 
anymore. Since the Remove command doesn't - don't use it. 

Anyway, after you press V to confirm the removal of the workfile, 
the disk will make a little noiseand the workfiles will begone. Now 
Quit the Filer and press 'E' to begin editing a new program. 
Because there is no workfile, the Editor will now prompt you for a 
file to load. Just press 'RETURN'. Enter the program below, remem- 
bering to type a semicolon after all the 'WRITE' and the first 
'WRITELN' statement. 

PROGRAM Text^Test; 
BEGIN 

WRITE ('This is the first part of the line, '); 

WRITE ('this is the second, '); 

WRITELN ('and this is the last.'); 

WRITELN ('This is another line.') 
END. 

After you finish, remember to press 'CONTROL C to accept the 
lines you just typed. Now hit 'Q' to exit the Editor and then 'U' to 
Update the workfile. Next, compile the program and press 'R' to 
execute the file. You should be greeted with 'This is the first part of 
the line, this is the second, and this is the last.' on one line, and on 
the next line will be the words 'This is another line.'. 

You just learned three new things about Pascal. In the 'WRITELN' 
statements we used before, there were only numbers. Now you 
can see that it can display textual information also. To get the 
'WRITELN' statement to print out text and not numbers, enclose 
what you want printed within single quote ' marks. 

Isn't that great? We can print out text in additon to numbers. But 
what is that 'WRITE' statement? If you remember the meaning of 
'WRITELN' you should see that they are quite similar. 'WRITE' prints 
out the information within its parenthesis to the screen, but doesn't 
drop on down to the next line when it is done. This explains why 
the first three Write statements print out only one line of text on the 
screen. 

To test our fledgling knowledge of Pascal, let's make a couple of 
intentional errors. Enter the Editor and delete the semicolon after 
the first 'WRITE' statement. Now Quit the Editor and Update the file. 
Compile the program and in the middle of the compilation you will 
get an error message. Press 'E' to enter the Editor to see the mistake. 
In a few moments the line "Illegal symbol (maybe missing or extra 
';' on line above)"will appear. Press the space bar to continue. The 
cursor will be right after the second 'WRITE'. 



See how nice the system is? It tells you almost exactly what you did 
wrong so you can correct it. This is a whole lot better than some 
language compilers, whose short error messages are undeci- 
pherable. 

A semicolon must always separate two consecutive statements. 
Since we deleted one in the above program, that gave us an error, 
you should be able to see why we got the error. But why aren't 
there semicolons between the 'BEGIN' and the first 'WRITE', and 
the last 'WRITELN' and the 'END.'? How can we justify this apparent 
contradiction? You probably see the answer. 'BEGIN' and 'END' 
are not statements! 

You should think of these non-statements as nothing more than the 
separators of different parts of the program. Statements within the 
separators need to be separated by semicolons, but semicolons 
dre not needed to separate the statements from the separators. 

This is one of the most important things we will learn. Since Pascal 
is block structured, and in each program there will be many small 
program pieces, there dre going to be a lot of 'BEGIN's and 'END'S. 
Though there are many of them, the are NOT statements. 

Get into the Filer and use the 'N' command to delete our workfile. 
Now Quit the Filer and enter the Editor. Type in the following 
program, Compile and run it. 

PROGRAM Compact; BEGIN WRITELN ('Wow, it works!') END. 

One of the nice features of the Pascal compiler is that it allows you 
to write your program in a free-form manner that is easy to read. As 
you can see the above program works just fine. In all of the 
previous programs, the extra lines and spaces were added only to 
make it more readable. The compiler can tell what you mean if you 
follow the few simple rules. 

There is no set way of adding spaces or formatting your program, 
some people add lines and lines of extra indentation etc. to make 
their programs as easi ly understood as possible. I can't force you to 
addthosespaces, but think of it this way. If you just finished writing 
a very long program and you had to debug (fix errors) it, which 
program would you rather read, the one with no indentation, or the 
one that has many extra spaces? 

Congratulations, by now you have reached an important level of 
understanding Apple /// Pascal. The thirty or so single letter 
commands that you have learned are the ones that you will use 
most of the time in the future. In the past few pages you used them 
to Edit, Compile, Run and change your first Pascal programs. In the 
coming months, the programs you type in will get a little longer and 
more complicated, but you will be doing the same things that we 
did today - Edit, Compile, Run and change your programs. 

It's about time to pack it in. You learned a lot about the Pascal 
system today. Next time we will learn some more of the com- 
mands of Pascal. If you like to work ahead, you should type in and 
compile the program on page 6 of the Programmers manual, and 
read through chapters 2 and 3. If you have any problems with this 
lesson, I will answer letters, so write me in care of ON THREE and 
keep on trying! 
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Manasins written information, that is what word processing 
is all about, and that is what Apple Writer /// does. How 
easy does it work? Are there any bugs in the system? These are the 
questions people ask, and these are the questions that I'm going to 
try to answer. 

Apple Writer /// 

This program is one in a series of word processing programs 
written by Paul Lutus. He wrote the popular Apple Writer ][ for the 
Apple ][, and this version is an extension of that program. However 
it's not just an Apple ][ copy (as many Apple /// programs are), 
but a completely new version that has some unbelievable features. 

As all word processors do, with Apple Writer /// you type 
information in on the keyboard and it is stored in the computers 
memory. Once you have it in the computer you can do all sorts of 
neat things to the text. Since this aspect of word processing isvery 
similar for all computers I'm not going to go into the detail of how 
each different function works. Instead I will tell of the features 
which makes this program different from the rest. 

This program requires a 128K Apple/// and just the internal disk 
drive to work. A printer and extra disk drive are optional but come 
in handy. One of the programs weak points is that if you have a 
256K computer, you still can only use about 64K of memory. In 
other words, don't go out and spend hundreds of dollars on a 
memory upgrade and expect Apple Writer /// to use the extra 
memory. I'm told that this will NOT be corrected in the future, so it 
may affect your purchase of this program. 

There sre three program disks in the package. It comes with two 
copy protected boot disks and one copyable utility disk. As is 
standard with Apple Special Delivery Software, they come with a 
90 day warranty. The copy protection scheme used discourages 
multiple writings to the disk, so try to get your system configuration 
right the first time. After you write a new SOS.DRIVER file on the disk 
a few times, it refuses to boot and gives you an I/O error. 

While we are on the subject of shortcomings, lets turn to the 
instruction manual for a moment. While fairly thorough and well 
written, the darn thing doesn't have an index! Any time you need to 
look up one of the many features of the program, you have to 
search through the Table of Contents. Since it is five pages long, 
you are in for a lot of searching. Even though they try to make up for 
no index with a tear out reference card, it isn't the same thing! I 
don't know why Apple allowed this, and as far as I'm concerned it 
is unexcusable! The whole reason for computers is to make our 
lives a little easier, and this type of instruction manual does not help 
- it hinders. 

The program has a variety of very nice features. As with most 
programs of this type, there is a 'Data' line at the top of the screen. 
Here you can find information on how much memory is left, how 
much is used, the current position of the cursor in the file and the 
pathname of the file you are working on. Unlike many other pro- 
grams, Apple Writer/// allows you to 'toggle' this line on and off. 
Thus, if you get tired of looking at it, one press of the 'ESCAPE' key 



will erase it and another will restore it! 

If you are new to word processing, there is a thing called 'Wrap- 
Around'. This feature allows you to type information into the 
computer and as the words reach the right side of the screen, if 
they won't fit on the line, the whole word is brought down to the 
next line. Thus you only need to insert a Carriage Return at the end 
of a paragraph. Apple Writer/// allows you to toggle this feature 
also. 

Another nice touch is the ability to 'see' these Carriage Returns. This 
is particularly helpful in the situation when you get a printout that 
you didn't expect. Sometimes you accidentally type in a Return 
and you don't know it. This feature allows you to see where all the 
Returns are in your text. 

When typing in text, one feature that I don't like is where the cursor 
is. Instead on being over the character, it goes between them, 
splitting up words as it goes. Just a small point that I don't care for. 

You can have a split screen display for working on one part of your 
file while displaying another. This is a very handy and sophisticated 
tool. Instead of relying on your memory when retyping in a com- 
mon phrase, you can use the split screen and see the other portion 
of the file! 

Apple Writer/// has the standard characterand word delete, but 
the way that it implements these functions leaves something to be 
desired. Some programs use the numeric keypad as a special 
functions area. One key to delete a word, another restore a word, 
etc. This word processor uses 'CONTROL W' to delete and restore 
a word. Since the Apple/// makes it possible for the programmer 
to make an extraordinary program, I sometimes wonder why many 
programmers don't fully use the abilities of the machine. 

Vou can toggle the word 'Wrap- Around' by pressing 'CONTROL Z'. 
This is another handy feature not normally found on word proces- 
sors at this level. Perhaps the single best (well, one of a few) 
features of this program is the built-in Help screens. These provide 
a summary of most all the features found in the language. By 
pressing Open Apple - Question mark, a menu appears. Simply 
type in the number of the command you want explained, and in a 
moment it is displayed on the screen. It Is so very helpful, that many 
of the newer Apple /// programs are incorporating it. 

Another of the remarkable things that Apple Writer ///does is the 
Load and Save command. Like other word processors, you can 
save and load a file to and from a disk. Unlike others, this program 
allows you to save portions of the file In memory to the disk, load a 
particular segment of the file on the disk, append a file in memory 
to a disk file and more! 

Vou can search a disk file for a particular phrase or string, and load it 
selectively into memory. This command lets you even load and 
save a file from the text in memory. Thus you can repeat sections of 
text very easily. You can also preview the contents of a disk file 
using the load command. When used, the text in the disk file is 
displayed on the screen but not stored in memory. The instruction 
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manual shows you how to access all of these features with good 
examples. 

Another of the features of Apple Writer/// is the SOS Commands 
Menu. Invoked by typing 'CONTROL O', you can Catalog the files 
on a disk drive, rename, lock, unlock, and delete files. With this 
menu you can also set the Prefix so you only have to type in a local 
pathname, and even look at and set the current date and time. 

The Catalog command has a slight problem that may give you a 
headache or two. It will only tell you the number of bytes in the file 
MOD 65536. Thus, if you have a very big file (> blocks), it will 
give you the wrong End Of File. 

The TAB' key is fully functional and will go to ever/ eighth column 
position when pressed. The user can very easily set a new Tab 
stop, delete an old one, or purge all Tab stops. You can also save 
the new tab settings to disk to be used later. 

Apple Writer /// allows the user to set up a glossary and later 
invoke the glossary entries as macros. Simply put, you can tell the 
computer that whenever you type 'CONTROL Ga', the words 
'Apple Writer ///' will appear. This allows you to write words or 
phrases that are difficult to type just once. From then on, only two 
key strokes will bring up any of the phrases you defined. 

There is even a feature that allows you to change the case of any 
word or phrase without having to retype it. Just press 'CONTROL C 
and then move the cursor over the word or character to be 
changed, and it will change case. 

One of the most interesting features is the ability to change the style 
of font that is printed on the text screen. There are four extra fonts 
on the boot disk and you can change to any one of them at any 
time. If you like your characters to have a slant, be gothic looking, or 
have any other style, Apple Writer /// can give it to you. 

The Find command lets you search through the text in memor/fora 
particular word or phrase and also lets you change it. Very power- 
ful, you can use this command with special delimiters to search for 
Returns, and 'even use wildcards to search for any sequence of 
characters. 

Underlining, superand subscriptsand footnotes are all supported, 
though some are a little hard to use. For instance, the underlining 
command forces you to replace any spaces within the text you 
want underlined to the underscore character. This is time consum- 
ing and is a very good example of what needs to be changed with 
this program. 

Since one of the most important parts of word processing is 
printing the text file to a printer, we will now discuss the strong and 
weak points of Apple Writer ///'s Print commands. 

To get into the 'Print Mode' of Apple Writer///, press 'CONTROL P' 
and then enter a question mark. Displayed now is a list of the 
present printing format values. You can change the margins, spec- 
ify how many lines to be printed per page, and even have page 
numbers and titles be printed on each page. 

You can set the number of blank lines to be printed between each 
printed lines. Thus single, double and triple spacing are ver/ easy. 



You can also change the device to which the text will be printed. 
However, if you send the text to the .CONSOLE, you will not be 
able to see the text as it will appear on the printed page because it 
does not have a left-right scrolling ability. This is a serious defi- 
ciency and should be corrected. 

At times you may want your printed text to be justified in a 
particular manner. You can force a left, center or right justification - 
but the fill justification feature has a ver/ serious problem which 
makes it unworkable. 

If you specify fill justification, spaces are added to the line, to line 
up both the right and left margins so they are flush. However, each 
line isfilljustified they same way. Starting at the left margin, spaces 
are added to the line to fill justify it. This Is a serious error because 
when you look at the printed page, there is more spacing at the left 
than at the right, and you get a section of text that is 'right heavy'. 

Second year computer science majors are taught that this is an 
unacceptable practice and are shown how to correct it. It is really 
very simple. When you need to fill justify a number of lines, choose 
a random starting point within the line where to start adding 
spaces. This method gives a truly random look to the spaces in 
printed text and is the standard method for formatting during a fill 
justify. I don't know why this program doesn't have this feature, and 
until it does I would suggest that you don't use the fill justify mode. 

While the print commands of Apple Writer /// are for the most 
part standard, it does allow you to paginate your documents by 
adding titles, page numbers etc. However it does have some 
problems that should be fixed. 

The last of Apple Writer ///'s features that we will discuss is WPL, 
or Word Processing Language. This is the most revolutionar/ feature 
of Apple Writer ///. What is it? Just a language within a language, 
essentially a Basic interpreter that allows you to automate many of 
the repetitious chores associated with word processing. 

You can use it to automatically print form letters, each with a 
different name and address that is stored in another file and is 
called up by WPL and inserted in the right places in your 
document. 

WPL will translate one series of statements to another quickly and 
easily. Persons who use typewriter shorthand can use WPL to 
translate it back into recognizable sentences without operator 
intervention. 

You can use WPL in a variety of tasks to do anything thatyou would 
have done by hand - only faster, automatically and it doesn't make 
mistakes! 

Since WPL is really a computer language, ON THREE will periodi- 
cally publish useful WPL programs and instructions on how to use 
them. We had hoped to have a special on WPL ready for this issue, 
but as usual we got behind and it didn't make the deadline. We 
will publish it next issue because it is a good introduction to Word 
Processing Language and tells just what makes WPL so revolution- 
ar/. If you have written a particularly interesting program in WPL I 
want to hear from you! 



February /March 1983 



37 



ONTHREE 



/// /// /// /// /// /// /// /// /// /// /// /// /// 



/// 



UtiUties Diskette 

One of the diskettes included with the Apple Writer/// packase 
is the Utilities disk. This contains a utility prosram which allows you 
to transfer Apple Writer ][ files to Apple Writer /// files and 
vice-versa. You can also use this prosram to transfer Mail List 
Manaser files to a form that can be used by Apple Writer ///. 
Once the Mail List Manager files are in the format for Apple Writer 
/// files, they can be used in form letters and other things that 
Apple Writer /// and WPL can do. 

The program is written in Pascal and if you have Pascal you can 
execute it as any other Pascal code file. If you want to do this, you 
must first copy the dependent Units from the Utilities Diskette 
'SYSTEM.LIBRARV to your own 'SYSTEM.LIBRARy for it to work. 

You must have one external drive for the program to work. The 
Apple Writer /// operating manual has instructions for using the 
Utilities diskette in Appendix C and D. If you use Apple Writer ][ 
and Apple Writer /// files, this utility is ver/ handy. 

Product Training Pak 

The Apple Writer/// Product Training Pak is a tutorial manual and 
diskette that will introduce you to the Apple Writer /// word 
processor. If you are new to computerized word processing this is 
a very helpful package to use to learn Apple Writer ///. If you are 
using your computer in your office and you want to teach your 
secretary how to use it, this manual is invaluable. 

Starting from the very simplest of commands, the tutorial teaches 
the novice user most all of the functions that are required to 
operate the word processor. Loading, and Saving of files are all 
covered, in addition to how to use the Help screens. 

Simple character insertion, deletion and replacement are covered. 
The manual also tells how to access the SOS commands menu and 
how to use It. Basic printing operations are also covered. 

Even WPL is given a few pages. The demonstration disk that comes 
with the Product Training Pak contains many example WPL pro- 
grams that the tutorial shows how to use. A form letter filling 
program automatically writes out letter after letter using a mailing 
list on another one of the disk files. WPL printing of files is also 
shown, as well as a program that changes fonts. 

Also on the disk are a number of very interesting files. They were 
originally deleted, but with a little expertise you can restore them 
(see 'Lazarus ///' in a future issue). One of them Is the text file of 
the Product Training Pak instruction manual! You will be able to see 
the instruction manual on your screen! 

Since the Product Training Pak is a very useful addition for novice 
users, I would recommend purchasing it when you buy the main 
program. If you have any fears about word processing, it will do a 
lot to alleviate them. 



recommend that you didn't buy it. There are quite a few things that 
should be changed in the program before it is one of the quality 
items that Apple /// users deserve. However, because Apple 
Writer/// has WPL, the good points outweigh the bad points and I 
think it Is a good word processor. 

Equipment used in this review: 

128K Apple/// 

1 external floppy drive 

Program: Apple Writer /// for the Apple /// 

Version: Interpreter created 9/18/81 

Contents: Program, Backup and Utilities Diskettes. 

User's manual. 
Programming language: Assembly and WPL 
Operating System: Standard SOS 
Copy Protected: Yes 
DiskWarranty:90days 
Backup disk included: Yes 
Cost: $225.00 

Program: Apple Writer /// Utilities 
Programming language: Pascal 
Operating System: Standard SOS 
Copy Protected: No 
Cost: Included with Apple Writer /// 

Product Training Pak: 
Contents: Tutorial manual 

Sample Data Files Diskette. 
Cost: $40.00 

The Bottom Line 

Apple Writer/// 

Performance: Good 
Documentation: Poor-Fair 
Ease of use: Fair-Good 
Error Handling: Good 
Over All Rating: B- 



Summary 

Apple Writer/// is certainly a good word processor, but should 
you purchase it for your computer? Well, that's your decision, but 
let me say that if Apple Writer /// didn't have WPL I would 
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New_page ('Press any key to continue') 
END; {. Of PROCEDURE Show_disk_inf o > 

PROCEDURE Do_it; i Performs the listing of the directory > 
BEGIN 

Get_root_inf o; i The root block has 12 files positions > 
Show_root_inf o; i plus a root volume name on it. > 
Get_f ile_info <12); 
IF <COut_Path <> '.CONSOLE') AND (Out_Path <> '#1')) THEN 

WRITE ('Writing.'); 
Show_f ilB_info (12); 
WHILE (NOT EOF (Infile)) DO 
BEGIN 
<*IOCHECK- > 

Count := BLOCKREAD (Infile, Block_buf, 1); 
{;*IOCHECK+ > 

Trap_IO_error; 

Get_f ile_inf o (13); i All other directory blocks have > 
Show_f ile_inf o (13) i 13 file positions available. > 
END; 
Show_di sk_i nf o 
END; { Of PROCEDURE Do_it > 

BEGIN € MAIN of Li st_SOS_Di rectory > 

Set_Error_types; 

Set _File_typ es ; 

Set_Out_devi ce; 

File_count := O; 

Line_count := O; 

Open_Di rectory ; 

Do_it; 
t*IOCHECK- > 

CLOSE (Infile); 

CLOSE (Device, LOCK); 
{*IOCHECK+ > 

Trap_IO_error 
END; < Of PROCEDURE Li st_SOS_Di rectory > 

BEGIN 

I This is the initialization, which occurs > 

<. before the host program is executed. > 
END. C Of UNIT List_Stuff > 

Crrato: Opps, a mistroke ! 

If you purchased the January Disk of the Month, you are no doubt 

ujondering luhy the program 'FONTD6MO' on the bock side of the 

disk doesn't uiork. To fix it make the folloiuing changes to the 

program. 

20 a*="a7.":i = l 

110 IF MID*(b*,3,4)<>"F0NT" THEN 10 

0:ELSE a*(i)=b*:n*=MID*(b*,16,l 

5):F0R j=l TO 15: IF MID«(n*,j,l 

)<>" " THEN NEXT 
340 IF k*<>" " THEN NEXT: ELSE END 

Since you con't save the program back to the diskette (it has no 
lurite-protect notch), save the file on another disk. To use, 
transfer the subdirectory 'FONTS' and all the files in it to the other 
disk. 
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Three Shorts — FinI! 

Once asain, kick off your boots and soothe that achins head to the 
sishts and sounds of ON THREE! The first two programs are graphic 
demos, while the last is a sound demo! It will give you a chorus of 
weird noises. 

To use the program "Bob's Blocks", just type it and and enter 
"RUN". No other files are needed. For the program "Bob's Lines", 
you need to have the file "BGRAF.INV" on a disk named "/BASIC" 
in one of your drives. If this file is elsewhere, make the appropriate 
change to line #100. If the program can not find that file, it will 
hang, and you will have to press the RESET key to stop it. 

The program "Bob's Noises??" uses the ".AUDIO" driver to gener- 
ate weird sounding noises. If the ".AUDIO" driver is not configured 
into your system, you will get an error message. 

ON THREE will pay $25 for any short demonstration program used 
in this space, so send in your favorite today, and we will see you 
next time in ON THREE. /// 



REK ttttutttttittttitttutittututmtttttt 

1 REH i Bob's Blocks t 

2 REM I » 

3 REH t This siiple little prograi shoHS hoM t 

4 REM i fast the Apple /// can display diff- I 

5 REH I erent colors on the screen. Just I 

6 REH I type in the prograa and enter 'RUN', t 

7 REH t This works best Hith a color aonitor t 

8 REM I but is still okay without one. i 

9 REH ItUtUttUttttttmtttttttMUtttttttttt 

10 )i.lem=0:x.riqhtX=0:y.topX=0:y.botX=0 

20 1 oop . col orX=0: bac k . col or2=20: d ear . vi e)»X=28 

30 blackX=0:»hiteiI=15 

40 text. fiode^=16: color, sodeil:! 

50 PRINT CHR»(text.«odeX);CHRIicolor.MdeX) 

60 HOME 

99 ON KBB BOTO 1000 

100 FOR loop.colorX=blackZ TO whiteZ 
110 60SUB 200 

120 PRINT CHR*!back.cQlorI);CHR$(loop.color2); 

130 PRINT CHR*(clear.vieN2); 

140 NEXT loop. col orX 

150 BOTO 100 

200 x.leftMND(l)l40:)!.rightX=RNBU)»40 

210 IF x.leftX>x.rightX THEN SNAP x.IeftX,x.right2 

220 y.topX=RNDil)»24:y.bofMND( 1)124 

230 IF y.topX>y.botJ THEN SNAP y.topZ,y.botX 

240 NINDON x.leftZ,y.topX TO x. right!, y.botX 

250 RETURN 

1000 IF K3D=27 THEN POP:TEXT:HOHE:END 

1010 ON KBD 6QT0 1000 

1020 RETURN 



REM tmtmtmttttttttttutiuttttuumtt 

1 REM t Bob's Lines t 

2 REM t t 

3 REH t Another very short program, it Mill t 

4 REH I draw lines on your graphics screen, t 

5 REH % It pickes randoi endpoints for the t 

6 REH I lines so you Hill get a colorful t 

7 REH I straw affect. To use, lake sure you t 

8 REM I have '/BASIC/BBRAF.INV on line. I 

9 REH HttttUttttttUtttttttHttttUtttttlOttt 

100 ON ERR INVOKE'/BASIC/BBRAF.INV" 

110 PERFORH initgrafix:OFF ERR 

120 xdistI=140:ydi5tJ=192:aodeX=3:bufX=l 

130 PERFORH grafixnde(ZBodeZ,:ibufX):PERFDRH grafixon 

140 PERFORM fillport 

199 ON KBD GOTO 1000 

200 FOR al=0 TO 1000 

210 PERFORM pencolor(IRND(l)tl6) 

220 PERFORH Boveto(2RNI)il)»xdistX,JRND(l)»ydistJ) 

230 PERFORM lineto(XRND(l)lxdistX,XRNDa)»ydistJ) 

240 NEXT 

250 SOTO 200 

1000 IF KBD=27 THEN POP:TEXT:HOHE:END 

1010 ON KBD 60T0 1000 

1020 RETURN 



REM tttttutttiMtunuHutttttttttmittttt 

1 REH i Bob's Noises?? I 

2 REH I I 

3 REM % Up to noN we have used this coluan to t 

4 REH % shoM off the graphics capabilities of t 

5 REH I the ///. This progran shows you soie t 

6 REM t of the different sounds the Apple /// t 

7 REH I can make. Just type it in and enter I 

B REH t the comaand 'RUN'. t 

9 REM uttttttttitttttttttmmtttttttumutt 

100 PRINT CHR$il4);:REM Turn off the screen 

110 countZ=0:tiae2=l:c.valJ=163B3:aodeX=l28:volX=i3 

120 0PENIl,".audio":B0T0 499 

200 PRINTtl;CHR$(BodeX);CHR*(volZ); 

210 PRINT»l;CHR$(count7.-256llNT!countX/25i))! 

220 PRINTIl;CHRi(INT(countX/25lb))5 

230 PRINTIliCHRJitiaeX-25itINT(tiaeZ/256)); 

240 PRINT#l;CHR»!INT(ti8eX/256)); 

250 RETURN 

499 ON KBD BOTO 1000 

500 FOR aX=l TO 1000 

510 countZ=INT(RND(l)lc.van) 

520 GOSUB 200 

530 NEXT 

540 60T0 500 

1000 IF KBD=27 THEN CL0SEI1:TEXT:H0HE:END 

1010 ON KBD BOTO 1000 

1020 RETURN 
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Disk Of the Month 



Callins all you busy professionals, would you like to have the 
programs in this month's issue? What's that? You don't have time to 
type them in yourself? Well, just buy the disk! 



How would you like a vs/orking clock/calendar for your Apple///? 
Just as it was originally intended, a plug in clockchip with a battery 
backup. 

With ON THREE O'Clock installed, any time you save or modify a 
file, the current date and time will be stored on disk. Thus you will 
now be able to tell which file you last worked on, etc. 

Extremely easy to install and adjust, this is the one you have been 
waiting for! 

This package contains comprehensive instructions and a Six Month 
Warranty! Try to get that deal anywhere else! 

What's the best part? - The price! While others are selling theirs for 
$60 and up, we have broken the $50 barrier. Heck, we broke the 
$40 barrier! 

For only $39.95 (plus $2.50 for postage and handling) you can get 
the best little clock in town! 

Group rates are as follows: 

2 - 9 clock sets: $3650 apiece + $5 total shipping 
10-24 clock sets: $33.25 apiece + $7 total shipping 
over 24 clock sets: $31 .00 apiece + $9 total shipping 

Group rates must have one mailing address. Please use the 
attached envelope for orders. If envelope is missing, send to: 

ON THREE 

Attn: ORDER DEPT. 

P.O. Box 3825 

Ventura, California 93006 



This disk contains all the programs contained in the Januar/and the 
February-March issues of ON THREE. Included are Disk Pak1 :, which 
will give you extra disk space; Disk Pak2, which lists the files on a 
directory using Pascal; both of the Key-Things programs; all of the 
Graphics and Sound Demos and more! 

To discourage piracy, we have priced these disks so low, that 
everyone can afford one. 

Buy one now for the low, low price of $9.95 (Plus $1 .50 for postage 
and handling). 

Group rates are as follows: 

2 - 9 disks: $7.50 apiece + $3 total shipping 

10-24 disks: $7.00 apiece + $4 total shipping 

over 24 disks: $6.50 apiece + $5 total shipping 

Group rates must have one mailing address. Please use the att- 
ached envelope for orders. If envelope is missing, send tO: 

ON THREE 

Attn: ORDER DEPT. 

P.O. Box 3825 

Ventura, California 93006 
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